System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact e4eb94b270cb202ae90ded23c8c78434677b62ec:


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 6e 61  ><head>.<meta na
0070: 6d 65 3d 22 76 69 65 77 70 6f 72 74 22 20 63 6f  me="viewport" co
0080: 6e 74 65 6e 74 3d 22 77 69 64 74 68 3d 64 65 76  ntent="width=dev
0090: 69 63 65 2d 77 69 64 74 68 2c 20 69 6e 69 74 69  ice-width, initi
00a0: 61 6c 2d 73 63 61 6c 65 3d 31 2e 30 22 3e 0a 3c  al-scale=1.0">.<
00b0: 6d 65 74 61 20 68 74 74 70 2d 65 71 75 69 76 3d  meta http-equiv=
00c0: 22 63 6f 6e 74 65 6e 74 2d 74 79 70 65 22 20 63  "content-type" c
00d0: 6f 6e 74 65 6e 74 3d 22 74 65 78 74 2f 68 74 6d  ontent="text/htm
00e0: 6c 3b 20 63 68 61 72 73 65 74 3d 55 54 46 2d 38  l; charset=UTF-8
00f0: 22 3e 0a 3c 6c 69 6e 6b 20 68 72 65 66 3d 22 73  ">.<link href="s
0100: 71 6c 69 74 65 2e 63 73 73 22 20 72 65 6c 3d 22  qlite.css" rel="
0110: 73 74 79 6c 65 73 68 65 65 74 22 3e 0a 3c 74 69  stylesheet">.<ti
0120: 74 6c 65 3e 54 68 65 20 56 69 72 74 75 61 6c 20  tle>The Virtual 
0130: 54 61 62 6c 65 20 4d 65 63 68 61 6e 69 73 6d 20  Table Mechanism 
0140: 4f 66 20 53 51 4c 69 74 65 3c 2f 74 69 74 6c 65  Of SQLite</title
0150: 3e 0a 3c 21 2d 2d 20 70 61 74 68 3d 20 2d 2d 3e  >.<!-- path= -->
0160: 0a 3c 2f 68 65 61 64 3e 0a 3c 62 6f 64 79 3e 0a  .</head>.<body>.
0170: 3c 64 69 76 20 63 6c 61 73 73 3d 6e 6f 73 65 61  <div class=nosea
0180: 72 63 68 3e 0a 3c 61 20 68 72 65 66 3d 22 69 6e  rch>.<a href="in
0190: 64 65 78 2e 68 74 6d 6c 22 3e 0a 3c 69 6d 67 20  dex.html">.<img 
01a0: 63 6c 61 73 73 3d 22 6c 6f 67 6f 22 20 73 72 63  class="logo" src
01b0: 3d 22 69 6d 61 67 65 73 2f 73 71 6c 69 74 65 33  ="images/sqlite3
01c0: 37 30 5f 62 61 6e 6e 65 72 2e 67 69 66 22 20 61  70_banner.gif" a
01d0: 6c 74 3d 22 53 51 4c 69 74 65 22 20 62 6f 72 64  lt="SQLite" bord
01e0: 65 72 3d 22 30 22 3e 0a 3c 2f 61 3e 0a 3c 64 69  er="0">.</a>.<di
01f0: 76 3e 3c 21 2d 2d 20 49 45 20 68 61 63 6b 20 74  v><!-- IE hack t
0200: 6f 20 70 72 65 76 65 6e 74 20 64 69 73 61 70 70  o prevent disapp
0210: 65 61 72 69 6e 67 20 6c 6f 67 6f 20 2d 2d 3e 3c  earing logo --><
0220: 2f 64 69 76 3e 0a 3c 64 69 76 20 63 6c 61 73 73  /div>.<div class
0230: 3d 22 74 61 67 6c 69 6e 65 20 64 65 73 6b 74 6f  ="tagline deskto
0240: 70 6f 6e 6c 79 22 3e 0a 53 6d 61 6c 6c 2e 20 46  ponly">.Small. F
0250: 61 73 74 2e 20 52 65 6c 69 61 62 6c 65 2e 3c 62  ast. Reliable.<b
0260: 72 3e 43 68 6f 6f 73 65 20 61 6e 79 20 74 68 72  r>Choose any thr
0270: 65 65 2e 0a 3c 2f 64 69 76 3e 0a 3c 64 69 76 20  ee..</div>.<div 
0280: 63 6c 61 73 73 3d 22 6d 65 6e 75 20 6d 61 69 6e  class="menu main
0290: 6d 65 6e 75 22 3e 0a 3c 75 6c 3e 0a 3c 6c 69 3e  menu">.<ul>.<li>
02a0: 3c 61 20 68 72 65 66 3d 22 69 6e 64 65 78 2e 68  <a href="index.h
02b0: 74 6d 6c 22 3e 48 6f 6d 65 3c 2f 61 3e 0a 3c 6c  tml">Home</a>.<l
02c0: 69 20 63 6c 61 73 73 3d 27 6d 6f 62 69 6c 65 6f  i class='mobileo
02d0: 6e 6c 79 27 3e 3c 61 20 68 72 65 66 3d 22 6a 61  nly'><a href="ja
02e0: 76 61 73 63 72 69 70 74 3a 76 6f 69 64 28 30 29  vascript:void(0)
02f0: 22 20 6f 6e 63 6c 69 63 6b 3d 27 74 6f 67 67 6c  " onclick='toggl
0300: 65 5f 64 69 76 28 22 73 75 62 6d 65 6e 75 22 29  e_div("submenu")
0310: 27 3e 4d 65 6e 75 3c 2f 61 3e 0a 3c 6c 69 20 63  '>Menu</a>.<li c
0320: 6c 61 73 73 3d 27 77 69 64 65 6f 6e 6c 79 27 3e  lass='wideonly'>
0330: 3c 61 20 68 72 65 66 3d 27 61 62 6f 75 74 2e 68  <a href='about.h
0340: 74 6d 6c 27 3e 41 62 6f 75 74 3c 2f 61 3e 0a 3c  tml'>About</a>.<
0350: 6c 69 20 63 6c 61 73 73 3d 27 64 65 73 6b 74 6f  li class='deskto
0360: 70 6f 6e 6c 79 27 3e 3c 61 20 68 72 65 66 3d 22  ponly'><a href="
0370: 64 6f 63 73 2e 68 74 6d 6c 22 3e 44 6f 63 75 6d  docs.html">Docum
0380: 65 6e 74 61 74 69 6f 6e 3c 2f 61 3e 0a 3c 6c 69  entation</a>.<li
0390: 20 63 6c 61 73 73 3d 27 64 65 73 6b 74 6f 70 6f   class='desktopo
03a0: 6e 6c 79 27 3e 3c 61 20 68 72 65 66 3d 22 64 6f  nly'><a href="do
03b0: 77 6e 6c 6f 61 64 2e 68 74 6d 6c 22 3e 44 6f 77  wnload.html">Dow
03c0: 6e 6c 6f 61 64 3c 2f 61 3e 0a 3c 6c 69 20 63 6c  nload</a>.<li cl
03d0: 61 73 73 3d 27 77 69 64 65 6f 6e 6c 79 27 3e 3c  ass='wideonly'><
03e0: 61 20 68 72 65 66 3d 27 63 6f 70 79 72 69 67 68  a href='copyrigh
03f0: 74 2e 68 74 6d 6c 27 3e 4c 69 63 65 6e 73 65 3c  t.html'>License<
0400: 2f 61 3e 0a 3c 6c 69 20 63 6c 61 73 73 3d 27 64  /a>.<li class='d
0410: 65 73 6b 74 6f 70 6f 6e 6c 79 27 3e 3c 61 20 68  esktoponly'><a h
0420: 72 65 66 3d 22 73 75 70 70 6f 72 74 2e 68 74 6d  ref="support.htm
0430: 6c 22 3e 53 75 70 70 6f 72 74 3c 2f 61 3e 0a 3c  l">Support</a>.<
0440: 6c 69 20 63 6c 61 73 73 3d 27 64 65 73 6b 74 6f  li class='deskto
0450: 70 6f 6e 6c 79 27 3e 3c 61 20 68 72 65 66 3d 22  ponly'><a href="
0460: 70 72 6f 73 75 70 70 6f 72 74 2e 68 74 6d 6c 22  prosupport.html"
0470: 3e 50 75 72 63 68 61 73 65 3c 2f 61 3e 0a 3c 6c  >Purchase</a>.<l
0480: 69 20 63 6c 61 73 73 3d 27 73 65 61 72 63 68 27  i class='search'
0490: 20 69 64 3d 27 73 65 61 72 63 68 5f 6d 65 6e 75   id='search_menu
04a0: 62 75 74 74 6f 6e 27 3e 0a 3c 61 20 68 72 65 66  button'>.<a href
04b0: 3d 22 6a 61 76 61 73 63 72 69 70 74 3a 76 6f 69  ="javascript:voi
04c0: 64 28 30 29 22 20 6f 6e 63 6c 69 63 6b 3d 27 74  d(0)" onclick='t
04d0: 6f 67 67 6c 65 5f 73 65 61 72 63 68 28 29 27 3e  oggle_search()'>
04e0: 53 65 61 72 63 68 3c 2f 61 3e 0a 3c 2f 75 6c 3e  Search</a>.</ul>
04f0: 0a 3c 2f 64 69 76 3e 0a 3c 64 69 76 20 63 6c 61  .</div>.<div cla
0500: 73 73 3d 22 6d 65 6e 75 20 73 75 62 6d 65 6e 75  ss="menu submenu
0510: 22 20 69 64 3d 22 73 75 62 6d 65 6e 75 22 3e 0a  " id="submenu">.
0520: 3c 75 6c 3e 0a 3c 6c 69 3e 3c 61 20 68 72 65 66  <ul>.<li><a href
0530: 3d 27 61 62 6f 75 74 2e 68 74 6d 6c 27 3e 41 62  ='about.html'>Ab
0540: 6f 75 74 3c 2f 61 3e 0a 3c 6c 69 3e 3c 61 20 68  out</a>.<li><a h
0550: 72 65 66 3d 27 64 6f 63 73 2e 68 74 6d 6c 27 3e  ref='docs.html'>
0560: 44 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 3c 2f 61  Documentation</a
0570: 3e 0a 3c 6c 69 3e 3c 61 20 68 72 65 66 3d 27 64  >.<li><a href='d
0580: 6f 77 6e 6c 6f 61 64 2e 68 74 6d 6c 27 3e 44 6f  ownload.html'>Do
0590: 77 6e 6c 6f 61 64 3c 2f 61 3e 0a 3c 6c 69 3e 3c  wnload</a>.<li><
05a0: 61 20 68 72 65 66 3d 27 73 75 70 70 6f 72 74 2e  a href='support.
05b0: 68 74 6d 6c 27 3e 53 75 70 70 6f 72 74 3c 2f 61  html'>Support</a
05c0: 3e 0a 3c 6c 69 3e 3c 61 20 68 72 65 66 3d 27 70  >.<li><a href='p
05d0: 72 6f 73 75 70 70 6f 72 74 2e 68 74 6d 6c 27 3e  rosupport.html'>
05e0: 50 75 72 63 68 61 73 65 3c 2f 61 3e 0a 3c 2f 75  Purchase</a>.</u
05f0: 6c 3e 0a 3c 2f 64 69 76 3e 0a 3c 64 69 76 20 63  l>.</div>.<div c
0600: 6c 61 73 73 3d 22 73 65 61 72 63 68 6d 65 6e 75  lass="searchmenu
0610: 22 20 69 64 3d 22 73 65 61 72 63 68 6d 65 6e 75  " id="searchmenu
0620: 22 3e 0a 3c 66 6f 72 6d 20 6d 65 74 68 6f 64 3d  ">.<form method=
0630: 22 47 45 54 22 20 61 63 74 69 6f 6e 3d 22 73 65  "GET" action="se
0640: 61 72 63 68 22 3e 0a 3c 73 65 6c 65 63 74 20 6e  arch">.<select n
0650: 61 6d 65 3d 22 73 22 20 69 64 3d 22 73 65 61 72  ame="s" id="sear
0660: 63 68 74 79 70 65 22 3e 0a 3c 6f 70 74 69 6f 6e  chtype">.<option
0670: 20 76 61 6c 75 65 3d 22 64 22 3e 53 65 61 72 63   value="d">Searc
0680: 68 20 44 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 3c  h Documentation<
0690: 2f 6f 70 74 69 6f 6e 3e 0a 3c 6f 70 74 69 6f 6e  /option>.<option
06a0: 20 76 61 6c 75 65 3d 22 63 22 3e 53 65 61 72 63   value="c">Searc
06b0: 68 20 43 68 61 6e 67 65 6c 6f 67 3c 2f 6f 70 74  h Changelog</opt
06c0: 69 6f 6e 3e 0a 3c 2f 73 65 6c 65 63 74 3e 0a 3c  ion>.</select>.<
06d0: 69 6e 70 75 74 20 74 79 70 65 3d 22 74 65 78 74  input type="text
06e0: 22 20 6e 61 6d 65 3d 22 71 22 20 69 64 3d 22 73  " name="q" id="s
06f0: 65 61 72 63 68 62 6f 78 22 20 76 61 6c 75 65 3d  earchbox" value=
0700: 22 22 3e 0a 3c 69 6e 70 75 74 20 74 79 70 65 3d  "">.<input type=
0710: 22 73 75 62 6d 69 74 22 20 76 61 6c 75 65 3d 22  "submit" value="
0720: 47 6f 22 3e 0a 3c 2f 66 6f 72 6d 3e 0a 3c 2f 64  Go">.</form>.</d
0730: 69 76 3e 0a 3c 2f 64 69 76 3e 0a 3c 73 63 72 69  iv>.</div>.<scri
0740: 70 74 3e 0a 66 75 6e 63 74 69 6f 6e 20 74 6f 67  pt>.function tog
0750: 67 6c 65 5f 64 69 76 28 6e 6d 29 20 7b 0a 76 61  gle_div(nm) {.va
0760: 72 20 77 20 3d 20 64 6f 63 75 6d 65 6e 74 2e 67  r w = document.g
0770: 65 74 45 6c 65 6d 65 6e 74 42 79 49 64 28 6e 6d  etElementById(nm
0780: 29 3b 0a 69 66 28 20 77 2e 73 74 79 6c 65 2e 64  );.if( w.style.d
0790: 69 73 70 6c 61 79 3d 3d 22 62 6c 6f 63 6b 22 20  isplay=="block" 
07a0: 29 7b 0a 77 2e 73 74 79 6c 65 2e 64 69 73 70 6c  ){.w.style.displ
07b0: 61 79 20 3d 20 22 6e 6f 6e 65 22 3b 0a 7d 65 6c  ay = "none";.}el
07c0: 73 65 7b 0a 77 2e 73 74 79 6c 65 2e 64 69 73 70  se{.w.style.disp
07d0: 6c 61 79 20 3d 20 22 62 6c 6f 63 6b 22 3b 0a 7d  lay = "block";.}
07e0: 0a 7d 0a 66 75 6e 63 74 69 6f 6e 20 74 6f 67 67  .}.function togg
07f0: 6c 65 5f 73 65 61 72 63 68 28 29 20 7b 0a 76 61  le_search() {.va
0800: 72 20 77 20 3d 20 64 6f 63 75 6d 65 6e 74 2e 67  r w = document.g
0810: 65 74 45 6c 65 6d 65 6e 74 42 79 49 64 28 22 73  etElementById("s
0820: 65 61 72 63 68 6d 65 6e 75 22 29 3b 0a 69 66 28  earchmenu");.if(
0830: 20 77 2e 73 74 79 6c 65 2e 64 69 73 70 6c 61 79   w.style.display
0840: 3d 3d 22 62 6c 6f 63 6b 22 20 29 7b 0a 77 2e 73  =="block" ){.w.s
0850: 74 79 6c 65 2e 64 69 73 70 6c 61 79 20 3d 20 22  tyle.display = "
0860: 6e 6f 6e 65 22 3b 0a 7d 20 65 6c 73 65 20 7b 0a  none";.} else {.
0870: 77 2e 73 74 79 6c 65 2e 64 69 73 70 6c 61 79 20  w.style.display 
0880: 3d 20 22 62 6c 6f 63 6b 22 3b 0a 73 65 74 54 69  = "block";.setTi
0890: 6d 65 6f 75 74 28 66 75 6e 63 74 69 6f 6e 28 29  meout(function()
08a0: 7b 0a 64 6f 63 75 6d 65 6e 74 2e 67 65 74 45 6c  {.document.getEl
08b0: 65 6d 65 6e 74 42 79 49 64 28 22 73 65 61 72 63  ementById("searc
08c0: 68 62 6f 78 22 29 2e 66 6f 63 75 73 28 29 0a 7d  hbox").focus().}
08d0: 2c 20 33 30 29 3b 0a 7d 0a 7d 0a 66 75 6e 63 74  , 30);.}.}.funct
08e0: 69 6f 6e 20 64 69 76 5f 6f 66 66 28 6e 6d 29 7b  ion div_off(nm){
08f0: 64 6f 63 75 6d 65 6e 74 2e 67 65 74 45 6c 65 6d  document.getElem
0900: 65 6e 74 42 79 49 64 28 6e 6d 29 2e 73 74 79 6c  entById(nm).styl
0910: 65 2e 64 69 73 70 6c 61 79 3d 22 6e 6f 6e 65 22  e.display="none"
0920: 3b 7d 0a 77 69 6e 64 6f 77 2e 6f 6e 62 65 66 6f  ;}.window.onbefo
0930: 72 65 75 6e 6c 6f 61 64 20 3d 20 66 75 6e 63 74  reunload = funct
0940: 69 6f 6e 28 65 29 7b 64 69 76 5f 6f 66 66 28 22  ion(e){div_off("
0950: 73 75 62 6d 65 6e 75 22 29 3b 7d 0a 2f 2a 20 44  submenu");}./* D
0960: 69 73 61 62 6c 65 20 74 68 65 20 53 65 61 72 63  isable the Searc
0970: 68 20 66 65 61 74 75 72 65 20 69 66 20 77 65 20  h feature if we 
0980: 61 72 65 20 6e 6f 74 20 6f 70 65 72 61 74 69 6e  are not operatin
0990: 67 20 66 72 6f 6d 20 43 47 49 2c 20 73 69 6e 63  g from CGI, sinc
09a0: 65 20 2a 2f 0a 2f 2a 20 53 65 61 72 63 68 20 69  e */./* Search i
09b0: 73 20 61 63 63 6f 6d 70 6c 69 73 68 65 64 20 75  s accomplished u
09c0: 73 69 6e 67 20 43 47 49 20 61 6e 64 20 77 69 6c  sing CGI and wil
09d0: 6c 20 6e 6f 74 20 77 6f 72 6b 20 77 69 74 68 6f  l not work witho
09e0: 75 74 20 69 74 2e 20 2a 2f 0a 69 66 28 20 21 6c  ut it. */.if( !l
09f0: 6f 63 61 74 69 6f 6e 2e 6f 72 69 67 69 6e 2e 6d  ocation.origin.m
0a00: 61 74 63 68 20 7c 7c 20 21 6c 6f 63 61 74 69 6f  atch || !locatio
0a10: 6e 2e 6f 72 69 67 69 6e 2e 6d 61 74 63 68 28 2f  n.origin.match(/
0a20: 68 74 74 70 2f 29 20 29 7b 0a 64 6f 63 75 6d 65  http/) ){.docume
0a30: 6e 74 2e 67 65 74 45 6c 65 6d 65 6e 74 42 79 49  nt.getElementByI
0a40: 64 28 22 73 65 61 72 63 68 5f 6d 65 6e 75 62 75  d("search_menubu
0a50: 74 74 6f 6e 22 29 2e 73 74 79 6c 65 2e 64 69 73  tton").style.dis
0a60: 70 6c 61 79 20 3d 20 22 6e 6f 6e 65 22 3b 0a 7d  play = "none";.}
0a70: 0a 2f 2a 20 55 73 65 64 20 62 79 20 74 68 65 20  ./* Used by the 
0a80: 48 69 64 65 2f 53 68 6f 77 20 62 75 74 74 6f 6e  Hide/Show button
0a90: 20 62 65 73 69 64 65 20 73 79 6e 74 61 78 20 64   beside syntax d
0aa0: 69 61 67 72 61 6d 73 2c 20 74 6f 20 74 6f 67 67  iagrams, to togg
0ab0: 6c 65 20 74 68 65 20 2a 2f 0a 66 75 6e 63 74 69  le the */.functi
0ac0: 6f 6e 20 68 69 64 65 6f 72 73 68 6f 77 28 62 74  on hideorshow(bt
0ad0: 6e 2c 6f 62 6a 29 7b 0a 76 61 72 20 78 20 3d 20  n,obj){.var x = 
0ae0: 64 6f 63 75 6d 65 6e 74 2e 67 65 74 45 6c 65 6d  document.getElem
0af0: 65 6e 74 42 79 49 64 28 6f 62 6a 29 3b 0a 76 61  entById(obj);.va
0b00: 72 20 62 20 3d 20 64 6f 63 75 6d 65 6e 74 2e 67  r b = document.g
0b10: 65 74 45 6c 65 6d 65 6e 74 42 79 49 64 28 62 74  etElementById(bt
0b20: 6e 29 3b 0a 69 66 28 20 78 2e 73 74 79 6c 65 2e  n);.if( x.style.
0b30: 64 69 73 70 6c 61 79 21 3d 27 6e 6f 6e 65 27 20  display!='none' 
0b40: 29 7b 0a 78 2e 73 74 79 6c 65 2e 64 69 73 70 6c  ){.x.style.displ
0b50: 61 79 20 3d 20 27 6e 6f 6e 65 27 3b 0a 62 2e 69  ay = 'none';.b.i
0b60: 6e 6e 65 72 48 54 4d 4c 3d 27 73 68 6f 77 27 3b  nnerHTML='show';
0b70: 0a 7d 65 6c 73 65 7b 0a 78 2e 73 74 79 6c 65 2e  .}else{.x.style.
0b80: 64 69 73 70 6c 61 79 20 3d 20 27 27 3b 0a 62 2e  display = '';.b.
0b90: 69 6e 6e 65 72 48 54 4d 4c 3d 27 68 69 64 65 27  innerHTML='hide'
0ba0: 3b 0a 7d 0a 72 65 74 75 72 6e 20 66 61 6c 73 65  ;.}.return false
0bb0: 3b 0a 7d 0a 3c 2f 73 63 72 69 70 74 3e 0a 3c 2f  ;.}.</script>.</
0bc0: 64 69 76 3e 0a 3c 64 69 76 20 63 6c 61 73 73 3d  div>.<div class=
0bd0: 66 61 6e 63 79 3e 0a 3c 64 69 76 20 63 6c 61 73  fancy>.<div clas
0be0: 73 3d 6e 6f 73 65 61 72 63 68 3e 0a 3c 64 69 76  s=nosearch>.<div
0bf0: 20 63 6c 61 73 73 3d 22 66 61 6e 63 79 5f 74 69   class="fancy_ti
0c00: 74 6c 65 22 3e 0a 54 68 65 20 56 69 72 74 75 61  tle">.The Virtua
0c10: 6c 20 54 61 62 6c 65 20 4d 65 63 68 61 6e 69 73  l Table Mechanis
0c20: 6d 20 4f 66 20 53 51 4c 69 74 65 0a 3c 2f 64 69  m Of SQLite.</di
0c30: 76 3e 0a 3c 64 69 76 20 63 6c 61 73 73 3d 22 66  v>.<div class="f
0c40: 61 6e 63 79 5f 74 6f 63 22 3e 0a 3c 61 20 6f 6e  ancy_toc">.<a on
0c50: 63 6c 69 63 6b 3d 22 74 6f 67 67 6c 65 5f 74 6f  click="toggle_to
0c60: 63 28 29 22 3e 0a 3c 73 70 61 6e 20 63 6c 61 73  c()">.<span clas
0c70: 73 3d 22 66 61 6e 63 79 5f 74 6f 63 5f 6d 61 72  s="fancy_toc_mar
0c80: 6b 22 20 69 64 3d 22 74 6f 63 5f 6d 6b 22 3e 26  k" id="toc_mk">&
0c90: 23 78 32 35 62 61 3b 3c 2f 73 70 61 6e 3e 0a 54  #x25ba;</span>.T
0ca0: 61 62 6c 65 20 4f 66 20 43 6f 6e 74 65 6e 74 73  able Of Contents
0cb0: 0a 3c 2f 61 3e 0a 3c 64 69 76 20 69 64 3d 22 74  .</a>.<div id="t
0cc0: 6f 63 5f 73 75 62 22 3e 3c 64 69 76 20 63 6c 61  oc_sub"><div cla
0cd0: 73 73 3d 22 66 61 6e 63 79 2d 74 6f 63 31 22 3e  ss="fancy-toc1">
0ce0: 3c 61 20 68 72 65 66 3d 22 23 69 6e 74 72 6f 64  <a href="#introd
0cf0: 75 63 74 69 6f 6e 22 3e 31 2e 20 49 6e 74 72 6f  uction">1. Intro
0d00: 64 75 63 74 69 6f 6e 3c 2f 61 3e 3c 2f 64 69 76  duction</a></div
0d10: 3e 0a 3c 64 69 76 20 63 6c 61 73 73 3d 22 66 61  >.<div class="fa
0d20: 6e 63 79 2d 74 6f 63 32 22 3e 3c 61 20 68 72 65  ncy-toc2"><a hre
0d30: 66 3d 22 23 75 73 61 67 65 22 3e 31 2e 31 2e 20  f="#usage">1.1. 
0d40: 55 73 61 67 65 3c 2f 61 3e 3c 2f 64 69 76 3e 0a  Usage</a></div>.
0d50: 3c 64 69 76 20 63 6c 61 73 73 3d 22 66 61 6e 63  <div class="fanc
0d60: 79 2d 74 6f 63 33 22 3e 3c 61 20 68 72 65 66 3d  y-toc3"><a href=
0d70: 22 23 74 65 6d 70 6f 72 61 72 79 5f 76 69 72 74  "#temporary_virt
0d80: 75 61 6c 5f 74 61 62 6c 65 73 22 3e 31 2e 31 2e  ual_tables">1.1.
0d90: 31 2e 20 54 65 6d 70 6f 72 61 72 79 20 76 69 72  1. Temporary vir
0da0: 74 75 61 6c 20 74 61 62 6c 65 73 3c 2f 61 3e 3c  tual tables</a><
0db0: 2f 64 69 76 3e 0a 3c 64 69 76 20 63 6c 61 73 73  /div>.<div class
0dc0: 3d 22 66 61 6e 63 79 2d 74 6f 63 33 22 3e 3c 61  ="fancy-toc3"><a
0dd0: 20 68 72 65 66 3d 22 23 65 70 6f 6e 79 6d 6f 75   href="#eponymou
0de0: 73 5f 76 69 72 74 75 61 6c 5f 74 61 62 6c 65 73  s_virtual_tables
0df0: 22 3e 31 2e 31 2e 32 2e 20 45 70 6f 6e 79 6d 6f  ">1.1.2. Eponymo
0e00: 75 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  us virtual table
0e10: 73 3c 2f 61 3e 3c 2f 64 69 76 3e 0a 3c 64 69 76  s</a></div>.<div
0e20: 20 63 6c 61 73 73 3d 22 66 61 6e 63 79 2d 74 6f   class="fancy-to
0e30: 63 33 22 3e 3c 61 20 68 72 65 66 3d 22 23 65 70  c3"><a href="#ep
0e40: 6f 6e 79 6d 6f 75 73 5f 6f 6e 6c 79 5f 76 69 72  onymous_only_vir
0e50: 74 75 61 6c 5f 74 61 62 6c 65 73 22 3e 31 2e 31  tual_tables">1.1
0e60: 2e 33 2e 20 45 70 6f 6e 79 6d 6f 75 73 2d 6f 6e  .3. Eponymous-on
0e70: 6c 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ly virtual table
0e80: 73 3c 2f 61 3e 3c 2f 64 69 76 3e 0a 3c 64 69 76  s</a></div>.<div
0e90: 20 63 6c 61 73 73 3d 22 66 61 6e 63 79 2d 74 6f   class="fancy-to
0ea0: 63 32 22 3e 3c 61 20 68 72 65 66 3d 22 23 69 6d  c2"><a href="#im
0eb0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 22 3e 31 2e  plementation">1.
0ec0: 32 2e 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  2. Implementatio
0ed0: 6e 3c 2f 61 3e 3c 2f 64 69 76 3e 0a 3c 64 69 76  n</a></div>.<div
0ee0: 20 63 6c 61 73 73 3d 22 66 61 6e 63 79 2d 74 6f   class="fancy-to
0ef0: 63 32 22 3e 3c 61 20 68 72 65 66 3d 22 23 76 69  c2"><a href="#vi
0f00: 72 74 75 61 6c 5f 74 61 62 6c 65 73 5f 61 6e 64  rtual_tables_and
0f10: 5f 73 68 61 72 65 64 5f 63 61 63 68 65 22 3e 31  _shared_cache">1
0f20: 2e 33 2e 20 56 69 72 74 75 61 6c 20 54 61 62 6c  .3. Virtual Tabl
0f30: 65 73 20 41 6e 64 20 53 68 61 72 65 64 20 43 61  es And Shared Ca
0f40: 63 68 65 3c 2f 61 3e 3c 2f 64 69 76 3e 0a 3c 64  che</a></div>.<d
0f50: 69 76 20 63 6c 61 73 73 3d 22 66 61 6e 63 79 2d  iv class="fancy-
0f60: 74 6f 63 32 22 3e 3c 61 20 68 72 65 66 3d 22 23  toc2"><a href="#
0f70: 63 72 65 61 74 69 6e 67 5f 6e 65 77 5f 76 69 72  creating_new_vir
0f80: 74 75 61 6c 5f 74 61 62 6c 65 5f 69 6d 70 6c 65  tual_table_imple
0f90: 6d 65 6e 74 61 74 69 6f 6e 73 22 3e 31 2e 34 2e  mentations">1.4.
0fa0: 20 43 72 65 61 74 69 6e 67 20 4e 65 77 20 56 69   Creating New Vi
0fb0: 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c  rtual Table Impl
0fc0: 65 6d 65 6e 74 61 74 69 6f 6e 73 3c 2f 61 3e 3c  ementations</a><
0fd0: 2f 64 69 76 3e 0a 3c 64 69 76 20 63 6c 61 73 73  /div>.<div class
0fe0: 3d 22 66 61 6e 63 79 2d 74 6f 63 31 22 3e 3c 61  ="fancy-toc1"><a
0ff0: 20 68 72 65 66 3d 22 23 76 69 72 74 75 61 6c 5f   href="#virtual_
1000: 74 61 62 6c 65 5f 6d 65 74 68 6f 64 73 22 3e 32  table_methods">2
1010: 2e 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  . Virtual Table 
1020: 4d 65 74 68 6f 64 73 3c 2f 61 3e 3c 2f 64 69 76  Methods</a></div
1030: 3e 0a 3c 64 69 76 20 63 6c 61 73 73 3d 22 66 61  >.<div class="fa
1040: 6e 63 79 2d 74 6f 63 32 22 3e 3c 61 20 68 72 65  ncy-toc2"><a hre
1050: 66 3d 22 23 74 68 65 5f 78 63 72 65 61 74 65 5f  f="#the_xcreate_
1060: 6d 65 74 68 6f 64 22 3e 32 2e 31 2e 20 54 68 65  method">2.1. The
1070: 20 78 43 72 65 61 74 65 20 4d 65 74 68 6f 64 3c   xCreate Method<
1080: 2f 61 3e 3c 2f 64 69 76 3e 0a 3c 64 69 76 20 63  /a></div>.<div c
1090: 6c 61 73 73 3d 22 66 61 6e 63 79 2d 74 6f 63 33  lass="fancy-toc3
10a0: 22 3e 3c 61 20 68 72 65 66 3d 22 23 68 69 64 64  "><a href="#hidd
10b0: 65 6e 5f 63 6f 6c 75 6d 6e 73 5f 69 6e 5f 76 69  en_columns_in_vi
10c0: 72 74 75 61 6c 5f 74 61 62 6c 65 73 22 3e 32 2e  rtual_tables">2.
10d0: 31 2e 31 2e 20 48 69 64 64 65 6e 20 63 6f 6c 75  1.1. Hidden colu
10e0: 6d 6e 73 20 69 6e 20 76 69 72 74 75 61 6c 20 74  mns in virtual t
10f0: 61 62 6c 65 73 3c 2f 61 3e 3c 2f 64 69 76 3e 0a  ables</a></div>.
1100: 3c 64 69 76 20 63 6c 61 73 73 3d 22 66 61 6e 63  <div class="fanc
1110: 79 2d 74 6f 63 33 22 3e 3c 61 20 68 72 65 66 3d  y-toc3"><a href=
1120: 22 23 74 61 62 6c 65 5f 76 61 6c 75 65 64 5f 66  "#table_valued_f
1130: 75 6e 63 74 69 6f 6e 73 22 3e 32 2e 31 2e 32 2e  unctions">2.1.2.
1140: 20 54 61 62 6c 65 2d 76 61 6c 75 65 64 20 66 75   Table-valued fu
1150: 6e 63 74 69 6f 6e 73 3c 2f 61 3e 3c 2f 64 69 76  nctions</a></div
1160: 3e 0a 3c 64 69 76 20 63 6c 61 73 73 3d 22 66 61  >.<div class="fa
1170: 6e 63 79 2d 74 6f 63 33 22 3e 3c 61 20 68 72 65  ncy-toc3"><a hre
1180: 66 3d 22 23 5f 77 69 74 68 6f 75 74 5f 72 6f 77  f="#_without_row
1190: 69 64 5f 76 69 72 74 75 61 6c 5f 74 61 62 6c 65  id_virtual_table
11a0: 73 5f 22 3e 32 2e 31 2e 33 2e 20 20 57 49 54 48  s_">2.1.3.  WITH
11b0: 4f 55 54 20 52 4f 57 49 44 20 56 69 72 74 75 61  OUT ROWID Virtua
11c0: 6c 20 54 61 62 6c 65 73 20 3c 2f 61 3e 3c 2f 64  l Tables </a></d
11d0: 69 76 3e 0a 3c 64 69 76 20 63 6c 61 73 73 3d 22  iv>.<div class="
11e0: 66 61 6e 63 79 2d 74 6f 63 32 22 3e 3c 61 20 68  fancy-toc2"><a h
11f0: 72 65 66 3d 22 23 74 68 65 5f 78 63 6f 6e 6e 65  ref="#the_xconne
1200: 63 74 5f 6d 65 74 68 6f 64 22 3e 32 2e 32 2e 20  ct_method">2.2. 
1210: 54 68 65 20 78 43 6f 6e 6e 65 63 74 20 4d 65 74  The xConnect Met
1220: 68 6f 64 3c 2f 61 3e 3c 2f 64 69 76 3e 0a 3c 64  hod</a></div>.<d
1230: 69 76 20 63 6c 61 73 73 3d 22 66 61 6e 63 79 2d  iv class="fancy-
1240: 74 6f 63 32 22 3e 3c 61 20 68 72 65 66 3d 22 23  toc2"><a href="#
1250: 74 68 65 5f 78 62 65 73 74 69 6e 64 65 78 5f 6d  the_xbestindex_m
1260: 65 74 68 6f 64 22 3e 32 2e 33 2e 20 54 68 65 20  ethod">2.3. The 
1270: 78 42 65 73 74 49 6e 64 65 78 20 4d 65 74 68 6f  xBestIndex Metho
1280: 64 3c 2f 61 3e 3c 2f 64 69 76 3e 0a 3c 64 69 76  d</a></div>.<div
1290: 20 63 6c 61 73 73 3d 22 66 61 6e 63 79 2d 74 6f   class="fancy-to
12a0: 63 33 22 3e 3c 61 20 68 72 65 66 3d 22 23 69 6e  c3"><a href="#in
12b0: 70 75 74 73 22 3e 32 2e 33 2e 31 2e 20 49 6e 70  puts">2.3.1. Inp
12c0: 75 74 73 3c 2f 61 3e 3c 2f 64 69 76 3e 0a 3c 64  uts</a></div>.<d
12d0: 69 76 20 63 6c 61 73 73 3d 22 66 61 6e 63 79 2d  iv class="fancy-
12e0: 74 6f 63 33 22 3e 3c 61 20 68 72 65 66 3d 22 23  toc3"><a href="#
12f0: 6f 75 74 70 75 74 73 22 3e 32 2e 33 2e 32 2e 20  outputs">2.3.2. 
1300: 4f 75 74 70 75 74 73 3c 2f 61 3e 3c 2f 64 69 76  Outputs</a></div
1310: 3e 0a 3c 64 69 76 20 63 6c 61 73 73 3d 22 66 61  >.<div class="fa
1320: 6e 63 79 2d 74 6f 63 32 22 3e 3c 61 20 68 72 65  ncy-toc2"><a hre
1330: 66 3d 22 23 74 68 65 5f 78 64 69 73 63 6f 6e 6e  f="#the_xdisconn
1340: 65 63 74 5f 6d 65 74 68 6f 64 22 3e 32 2e 34 2e  ect_method">2.4.
1350: 20 54 68 65 20 78 44 69 73 63 6f 6e 6e 65 63 74   The xDisconnect
1360: 20 4d 65 74 68 6f 64 3c 2f 61 3e 3c 2f 64 69 76   Method</a></div
1370: 3e 0a 3c 64 69 76 20 63 6c 61 73 73 3d 22 66 61  >.<div class="fa
1380: 6e 63 79 2d 74 6f 63 32 22 3e 3c 61 20 68 72 65  ncy-toc2"><a hre
1390: 66 3d 22 23 74 68 65 5f 78 64 65 73 74 72 6f 79  f="#the_xdestroy
13a0: 5f 6d 65 74 68 6f 64 22 3e 32 2e 35 2e 20 54 68  _method">2.5. Th
13b0: 65 20 78 44 65 73 74 72 6f 79 20 4d 65 74 68 6f  e xDestroy Metho
13c0: 64 3c 2f 61 3e 3c 2f 64 69 76 3e 0a 3c 64 69 76  d</a></div>.<div
13d0: 20 63 6c 61 73 73 3d 22 66 61 6e 63 79 2d 74 6f   class="fancy-to
13e0: 63 32 22 3e 3c 61 20 68 72 65 66 3d 22 23 74 68  c2"><a href="#th
13f0: 65 5f 78 6f 70 65 6e 5f 6d 65 74 68 6f 64 22 3e  e_xopen_method">
1400: 32 2e 36 2e 20 54 68 65 20 78 4f 70 65 6e 20 4d  2.6. The xOpen M
1410: 65 74 68 6f 64 3c 2f 61 3e 3c 2f 64 69 76 3e 0a  ethod</a></div>.
1420: 3c 64 69 76 20 63 6c 61 73 73 3d 22 66 61 6e 63  <div class="fanc
1430: 79 2d 74 6f 63 32 22 3e 3c 61 20 68 72 65 66 3d  y-toc2"><a href=
1440: 22 23 74 68 65 5f 78 63 6c 6f 73 65 5f 6d 65 74  "#the_xclose_met
1450: 68 6f 64 22 3e 32 2e 37 2e 20 54 68 65 20 78 43  hod">2.7. The xC
1460: 6c 6f 73 65 20 4d 65 74 68 6f 64 3c 2f 61 3e 3c  lose Method</a><
1470: 2f 64 69 76 3e 0a 3c 64 69 76 20 63 6c 61 73 73  /div>.<div class
1480: 3d 22 66 61 6e 63 79 2d 74 6f 63 32 22 3e 3c 61  ="fancy-toc2"><a
1490: 20 68 72 65 66 3d 22 23 74 68 65 5f 78 65 6f 66   href="#the_xeof
14a0: 5f 6d 65 74 68 6f 64 22 3e 32 2e 38 2e 20 54 68  _method">2.8. Th
14b0: 65 20 78 45 6f 66 20 4d 65 74 68 6f 64 3c 2f 61  e xEof Method</a
14c0: 3e 3c 2f 64 69 76 3e 0a 3c 64 69 76 20 63 6c 61  ></div>.<div cla
14d0: 73 73 3d 22 66 61 6e 63 79 2d 74 6f 63 32 22 3e  ss="fancy-toc2">
14e0: 3c 61 20 68 72 65 66 3d 22 23 74 68 65 5f 78 66  <a href="#the_xf
14f0: 69 6c 74 65 72 5f 6d 65 74 68 6f 64 22 3e 32 2e  ilter_method">2.
1500: 39 2e 20 54 68 65 20 78 46 69 6c 74 65 72 20 4d  9. The xFilter M
1510: 65 74 68 6f 64 3c 2f 61 3e 3c 2f 64 69 76 3e 0a  ethod</a></div>.
1520: 3c 64 69 76 20 63 6c 61 73 73 3d 22 66 61 6e 63  <div class="fanc
1530: 79 2d 74 6f 63 32 22 3e 3c 61 20 68 72 65 66 3d  y-toc2"><a href=
1540: 22 23 74 68 65 5f 78 6e 65 78 74 5f 6d 65 74 68  "#the_xnext_meth
1550: 6f 64 22 3e 32 2e 31 30 2e 20 54 68 65 20 78 4e  od">2.10. The xN
1560: 65 78 74 20 4d 65 74 68 6f 64 3c 2f 61 3e 3c 2f  ext Method</a></
1570: 64 69 76 3e 0a 3c 64 69 76 20 63 6c 61 73 73 3d  div>.<div class=
1580: 22 66 61 6e 63 79 2d 74 6f 63 32 22 3e 3c 61 20  "fancy-toc2"><a 
1590: 68 72 65 66 3d 22 23 74 68 65 5f 78 63 6f 6c 75  href="#the_xcolu
15a0: 6d 6e 5f 6d 65 74 68 6f 64 22 3e 32 2e 31 31 2e  mn_method">2.11.
15b0: 20 54 68 65 20 78 43 6f 6c 75 6d 6e 20 4d 65 74   The xColumn Met
15c0: 68 6f 64 3c 2f 61 3e 3c 2f 64 69 76 3e 0a 3c 64  hod</a></div>.<d
15d0: 69 76 20 63 6c 61 73 73 3d 22 66 61 6e 63 79 2d  iv class="fancy-
15e0: 74 6f 63 32 22 3e 3c 61 20 68 72 65 66 3d 22 23  toc2"><a href="#
15f0: 74 68 65 5f 78 72 6f 77 69 64 5f 6d 65 74 68 6f  the_xrowid_metho
1600: 64 22 3e 32 2e 31 32 2e 20 54 68 65 20 78 52 6f  d">2.12. The xRo
1610: 77 69 64 20 4d 65 74 68 6f 64 3c 2f 61 3e 3c 2f  wid Method</a></
1620: 64 69 76 3e 0a 3c 64 69 76 20 63 6c 61 73 73 3d  div>.<div class=
1630: 22 66 61 6e 63 79 2d 74 6f 63 32 22 3e 3c 61 20  "fancy-toc2"><a 
1640: 68 72 65 66 3d 22 23 74 68 65 5f 78 75 70 64 61  href="#the_xupda
1650: 74 65 5f 6d 65 74 68 6f 64 22 3e 32 2e 31 33 2e  te_method">2.13.
1660: 20 54 68 65 20 78 55 70 64 61 74 65 20 4d 65 74   The xUpdate Met
1670: 68 6f 64 3c 2f 61 3e 3c 2f 64 69 76 3e 0a 3c 64  hod</a></div>.<d
1680: 69 76 20 63 6c 61 73 73 3d 22 66 61 6e 63 79 2d  iv class="fancy-
1690: 74 6f 63 32 22 3e 3c 61 20 68 72 65 66 3d 22 23  toc2"><a href="#
16a0: 74 68 65 5f 78 66 69 6e 64 66 75 6e 63 74 69 6f  the_xfindfunctio
16b0: 6e 5f 6d 65 74 68 6f 64 22 3e 32 2e 31 34 2e 20  n_method">2.14. 
16c0: 54 68 65 20 78 46 69 6e 64 46 75 6e 63 74 69 6f  The xFindFunctio
16d0: 6e 20 4d 65 74 68 6f 64 3c 2f 61 3e 3c 2f 64 69  n Method</a></di
16e0: 76 3e 0a 3c 64 69 76 20 63 6c 61 73 73 3d 22 66  v>.<div class="f
16f0: 61 6e 63 79 2d 74 6f 63 32 22 3e 3c 61 20 68 72  ancy-toc2"><a hr
1700: 65 66 3d 22 23 74 68 65 5f 78 62 65 67 69 6e 5f  ef="#the_xbegin_
1710: 6d 65 74 68 6f 64 22 3e 32 2e 31 35 2e 20 54 68  method">2.15. Th
1720: 65 20 78 42 65 67 69 6e 20 4d 65 74 68 6f 64 3c  e xBegin Method<
1730: 2f 61 3e 3c 2f 64 69 76 3e 0a 3c 64 69 76 20 63  /a></div>.<div c
1740: 6c 61 73 73 3d 22 66 61 6e 63 79 2d 74 6f 63 32  lass="fancy-toc2
1750: 22 3e 3c 61 20 68 72 65 66 3d 22 23 74 68 65 5f  "><a href="#the_
1760: 78 73 79 6e 63 5f 6d 65 74 68 6f 64 22 3e 32 2e  xsync_method">2.
1770: 31 36 2e 20 54 68 65 20 78 53 79 6e 63 20 4d 65  16. The xSync Me
1780: 74 68 6f 64 3c 2f 61 3e 3c 2f 64 69 76 3e 0a 3c  thod</a></div>.<
1790: 64 69 76 20 63 6c 61 73 73 3d 22 66 61 6e 63 79  div class="fancy
17a0: 2d 74 6f 63 32 22 3e 3c 61 20 68 72 65 66 3d 22  -toc2"><a href="
17b0: 23 74 68 65 5f 78 63 6f 6d 6d 69 74 5f 6d 65 74  #the_xcommit_met
17c0: 68 6f 64 22 3e 32 2e 31 37 2e 20 54 68 65 20 78  hod">2.17. The x
17d0: 43 6f 6d 6d 69 74 20 4d 65 74 68 6f 64 3c 2f 61  Commit Method</a
17e0: 3e 3c 2f 64 69 76 3e 0a 3c 64 69 76 20 63 6c 61  ></div>.<div cla
17f0: 73 73 3d 22 66 61 6e 63 79 2d 74 6f 63 32 22 3e  ss="fancy-toc2">
1800: 3c 61 20 68 72 65 66 3d 22 23 74 68 65 5f 78 72  <a href="#the_xr
1810: 6f 6c 6c 62 61 63 6b 5f 6d 65 74 68 6f 64 22 3e  ollback_method">
1820: 32 2e 31 38 2e 20 54 68 65 20 78 52 6f 6c 6c 62  2.18. The xRollb
1830: 61 63 6b 20 4d 65 74 68 6f 64 3c 2f 61 3e 3c 2f  ack Method</a></
1840: 64 69 76 3e 0a 3c 64 69 76 20 63 6c 61 73 73 3d  div>.<div class=
1850: 22 66 61 6e 63 79 2d 74 6f 63 32 22 3e 3c 61 20  "fancy-toc2"><a 
1860: 68 72 65 66 3d 22 23 74 68 65 5f 78 72 65 6e 61  href="#the_xrena
1870: 6d 65 5f 6d 65 74 68 6f 64 22 3e 32 2e 31 39 2e  me_method">2.19.
1880: 20 54 68 65 20 78 52 65 6e 61 6d 65 20 4d 65 74   The xRename Met
1890: 68 6f 64 3c 2f 61 3e 3c 2f 64 69 76 3e 0a 3c 64  hod</a></div>.<d
18a0: 69 76 20 63 6c 61 73 73 3d 22 66 61 6e 63 79 2d  iv class="fancy-
18b0: 74 6f 63 32 22 3e 3c 61 20 68 72 65 66 3d 22 23  toc2"><a href="#
18c0: 74 68 65 5f 78 73 61 76 65 70 6f 69 6e 74 5f 78  the_xsavepoint_x
18d0: 72 65 6c 65 61 73 65 5f 61 6e 64 5f 78 72 6f 6c  release_and_xrol
18e0: 6c 62 61 63 6b 74 6f 5f 6d 65 74 68 6f 64 73 22  lbackto_methods"
18f0: 3e 32 2e 32 30 2e 20 54 68 65 20 78 53 61 76 65  >2.20. The xSave
1900: 70 6f 69 6e 74 2c 20 78 52 65 6c 65 61 73 65 2c  point, xRelease,
1910: 20 61 6e 64 20 78 52 6f 6c 6c 62 61 63 6b 54 6f   and xRollbackTo
1920: 20 4d 65 74 68 6f 64 73 3c 2f 61 3e 3c 2f 64 69   Methods</a></di
1930: 76 3e 0a 3c 2f 64 69 76 3e 0a 3c 2f 64 69 76 3e  v>.</div>.</div>
1940: 0a 3c 73 63 72 69 70 74 3e 0a 66 75 6e 63 74 69  .<script>.functi
1950: 6f 6e 20 74 6f 67 67 6c 65 5f 74 6f 63 28 29 7b  on toggle_toc(){
1960: 0a 76 61 72 20 73 75 62 20 3d 20 64 6f 63 75 6d  .var sub = docum
1970: 65 6e 74 2e 67 65 74 45 6c 65 6d 65 6e 74 42 79  ent.getElementBy
1980: 49 64 28 22 74 6f 63 5f 73 75 62 22 29 0a 76 61  Id("toc_sub").va
1990: 72 20 6d 6b 20 3d 20 64 6f 63 75 6d 65 6e 74 2e  r mk = document.
19a0: 67 65 74 45 6c 65 6d 65 6e 74 42 79 49 64 28 22  getElementById("
19b0: 74 6f 63 5f 6d 6b 22 29 0a 69 66 28 20 73 75 62  toc_mk").if( sub
19c0: 2e 73 74 79 6c 65 2e 64 69 73 70 6c 61 79 21 3d  .style.display!=
19d0: 22 62 6c 6f 63 6b 22 20 29 7b 0a 73 75 62 2e 73  "block" ){.sub.s
19e0: 74 79 6c 65 2e 64 69 73 70 6c 61 79 20 3d 20 22  tyle.display = "
19f0: 62 6c 6f 63 6b 22 3b 0a 6d 6b 2e 69 6e 6e 65 72  block";.mk.inner
1a00: 48 54 4d 4c 20 3d 20 22 26 23 78 32 35 62 63 3b  HTML = "&#x25bc;
1a10: 22 3b 0a 7d 20 65 6c 73 65 20 7b 0a 73 75 62 2e  ";.} else {.sub.
1a20: 73 74 79 6c 65 2e 64 69 73 70 6c 61 79 20 3d 20  style.display = 
1a30: 22 6e 6f 6e 65 22 3b 0a 6d 6b 2e 69 6e 6e 65 72  "none";.mk.inner
1a40: 48 54 4d 4c 20 3d 20 22 26 23 78 32 35 62 61 3b  HTML = "&#x25ba;
1a50: 22 3b 0a 7d 0a 7d 0a 3c 2f 73 63 72 69 70 74 3e  ";.}.}.</script>
1a60: 0a 3c 2f 64 69 76 3e 0a 0a 0a 0a 0a 0a 0a 3c 68  .</div>.......<h
1a70: 31 20 69 64 3d 22 69 6e 74 72 6f 64 75 63 74 69  1 id="introducti
1a80: 6f 6e 22 3e 3c 73 70 61 6e 3e 31 2e 20 3c 2f 73  on"><span>1. </s
1a90: 70 61 6e 3e 49 6e 74 72 6f 64 75 63 74 69 6f 6e  pan>Introduction
1aa0: 3c 2f 68 31 3e 0a 0a 3c 70 3e 41 20 76 69 72 74  </h1>..<p>A virt
1ab0: 75 61 6c 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ual table is an 
1ac0: 6f 62 6a 65 63 74 20 74 68 61 74 20 69 73 20 72  object that is r
1ad0: 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 61  egistered with a
1ae0: 6e 20 6f 70 65 6e 20 53 51 4c 69 74 65 0a 3c 61  n open SQLite.<a
1af0: 20 68 72 65 66 3d 22 63 33 72 65 66 2f 73 71 6c   href="c3ref/sql
1b00: 69 74 65 33 2e 68 74 6d 6c 22 3e 64 61 74 61 62  ite3.html">datab
1b10: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 3c 2f  ase connection</
1b20: 61 3e 2e 20 46 72 6f 6d 20 74 68 65 20 70 65 72  a>. From the per
1b30: 73 70 65 63 74 69 76 65 20 6f 66 20 61 6e 20 53  spective of an S
1b40: 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 0a 74 68  QL statement,.th
1b50: 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
1b60: 6f 62 6a 65 63 74 20 6c 6f 6f 6b 73 20 6c 69 6b  object looks lik
1b70: 65 20 61 6e 79 20 6f 74 68 65 72 20 74 61 62 6c  e any other tabl
1b80: 65 20 6f 72 20 76 69 65 77 2e 20 0a 42 75 74 20  e or view. .But 
1b90: 62 65 68 69 6e 64 20 74 68 65 20 73 63 65 6e 65  behind the scene
1ba0: 73 2c 20 71 75 65 72 69 65 73 20 61 6e 64 20 75  s, queries and u
1bb0: 70 64 61 74 65 73 20 6f 6e 20 61 20 76 69 72 74  pdates on a virt
1bc0: 75 61 6c 20 74 61 62 6c 65 0a 69 6e 76 6f 6b 65  ual table.invoke
1bd0: 20 63 61 6c 6c 62 61 63 6b 20 6d 65 74 68 6f 64   callback method
1be0: 73 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c  s of the virtual
1bf0: 20 74 61 62 6c 65 20 6f 62 6a 65 63 74 20 69 6e   table object in
1c00: 73 74 65 61 64 20 6f 66 0a 72 65 61 64 69 6e 67  stead of.reading
1c10: 20 61 6e 64 20 77 72 69 74 69 6e 67 20 6f 6e 20   and writing on 
1c20: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
1c30: 65 2e 0a 0a 3c 2f 70 3e 3c 70 3e 54 68 65 20 76  e...</p><p>The v
1c40: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 63  irtual table mec
1c50: 68 61 6e 69 73 6d 20 61 6c 6c 6f 77 73 20 61 6e  hanism allows an
1c60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
1c70: 70 75 62 6c 69 73 68 0a 69 6e 74 65 72 66 61 63  publish.interfac
1c80: 65 73 20 74 68 61 74 20 61 72 65 20 61 63 63 65  es that are acce
1c90: 73 73 69 62 6c 65 20 66 72 6f 6d 20 53 51 4c 20  ssible from SQL 
1ca0: 73 74 61 74 65 6d 65 6e 74 73 20 61 73 20 69 66  statements as if
1cb0: 20 74 68 65 79 20 77 65 72 65 0a 74 61 62 6c 65   they were.table
1cc0: 73 2e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  s. SQL statement
1cd0: 73 20 63 61 6e 20 64 6f 20 61 6c 6d 6f 73 74 20  s can do almost 
1ce0: 61 6e 79 74 68 69 6e 67 20 74 6f 20 61 0a 76 69  anything to a.vi
1cf0: 72 74 75 61 6c 20 74 61 62 6c 65 20 74 68 61 74  rtual table that
1d00: 20 74 68 65 79 20 63 61 6e 20 64 6f 20 74 6f 20   they can do to 
1d10: 61 20 72 65 61 6c 20 74 61 62 6c 65 2c 20 77 69  a real table, wi
1d20: 74 68 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  th the following
1d30: 0a 65 78 63 65 70 74 69 6f 6e 73 3a 0a 0a 3c 2f  .exceptions:..</
1d40: 70 3e 3c 70 3e 0a 3c 2f 70 3e 3c 75 6c 3e 0a 3c  p><p>.</p><ul>.<
1d50: 6c 69 3e 20 4f 6e 65 20 63 61 6e 6e 6f 74 20 63  li> One cannot c
1d60: 72 65 61 74 65 20 61 20 74 72 69 67 67 65 72 20  reate a trigger 
1d70: 6f 6e 20 61 20 76 69 72 74 75 61 6c 20 74 61 62  on a virtual tab
1d80: 6c 65 2e 0a 3c 2f 6c 69 3e 3c 6c 69 3e 20 4f 6e  le..</li><li> On
1d90: 65 20 63 61 6e 6e 6f 74 20 63 72 65 61 74 65 20  e cannot create 
1da0: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 64 69 63  additional indic
1db0: 65 73 20 6f 6e 20 61 20 76 69 72 74 75 61 6c 20  es on a virtual 
1dc0: 74 61 62 6c 65 2e 20 0a 20 20 20 20 20 28 56 69  table. .     (Vi
1dd0: 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e  rtual tables can
1de0: 20 68 61 76 65 20 69 6e 64 69 63 65 73 20 62 75   have indices bu
1df0: 74 20 74 68 61 74 20 6d 75 73 74 20 62 65 20 62  t that must be b
1e00: 75 69 6c 74 20 69 6e 74 6f 0a 20 20 20 20 20 74  uilt into.     t
1e10: 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
1e20: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
1e30: 20 20 49 6e 64 69 63 65 73 20 63 61 6e 6e 6f 74    Indices cannot
1e40: 20 62 65 20 61 64 64 65 64 0a 20 20 20 20 20 73   be added.     s
1e50: 65 70 61 72 61 74 65 6c 79 20 75 73 69 6e 67 20  eparately using 
1e60: 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 63 72  <a href="lang_cr
1e70: 65 61 74 65 69 6e 64 65 78 2e 68 74 6d 6c 22 3e  eateindex.html">
1e80: 43 52 45 41 54 45 20 49 4e 44 45 58 3c 2f 61 3e  CREATE INDEX</a>
1e90: 20 73 74 61 74 65 6d 65 6e 74 73 2e 29 0a 3c 2f   statements.).</
1ea0: 6c 69 3e 3c 6c 69 3e 20 4f 6e 65 20 63 61 6e 6e  li><li> One cann
1eb0: 6f 74 20 72 75 6e 20 3c 61 20 68 72 65 66 3d 22  ot run <a href="
1ec0: 6c 61 6e 67 5f 61 6c 74 65 72 74 61 62 6c 65 2e  lang_altertable.
1ed0: 68 74 6d 6c 22 3e 41 4c 54 45 52 20 54 41 42 4c  html">ALTER TABL
1ee0: 45 20 2e 2e 2e 20 41 44 44 20 43 4f 4c 55 4d 4e  E ... ADD COLUMN
1ef0: 3c 2f 61 3e 0a 20 20 20 20 20 63 6f 6d 6d 61 6e  </a>.     comman
1f00: 64 73 20 61 67 61 69 6e 73 74 20 61 20 76 69 72  ds against a vir
1f10: 74 75 61 6c 20 74 61 62 6c 65 2e 0a 3c 2f 6c 69  tual table..</li
1f20: 3e 3c 2f 75 6c 3e 0a 0a 3c 70 3e 49 6e 64 69 76  ></ul>..<p>Indiv
1f30: 69 64 75 61 6c 20 76 69 72 74 75 61 6c 20 74 61  idual virtual ta
1f40: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
1f50: 6f 6e 73 20 6d 69 67 68 74 20 69 6d 70 6f 73 65  ons might impose
1f60: 20 61 64 64 69 74 69 6f 6e 61 6c 0a 63 6f 6e 73   additional.cons
1f70: 74 72 61 69 6e 74 73 2e 20 46 6f 72 20 65 78 61  traints. For exa
1f80: 6d 70 6c 65 2c 20 73 6f 6d 65 20 76 69 72 74 75  mple, some virtu
1f90: 61 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  al implementatio
1fa0: 6e 73 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65  ns might provide
1fb0: 0a 72 65 61 64 2d 6f 6e 6c 79 20 74 61 62 6c 65  .read-only table
1fc0: 73 2e 20 4f 72 20 73 6f 6d 65 20 76 69 72 74 75  s. Or some virtu
1fd0: 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  al table impleme
1fe0: 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61  ntations might a
1ff0: 6c 6c 6f 77 0a 3c 61 20 68 72 65 66 3d 22 6c 61  llow.<a href="la
2000: 6e 67 5f 69 6e 73 65 72 74 2e 68 74 6d 6c 22 3e  ng_insert.html">
2010: 49 4e 53 45 52 54 3c 2f 61 3e 20 6f 72 20 3c 61  INSERT</a> or <a
2020: 20 68 72 65 66 3d 22 6c 61 6e 67 5f 64 65 6c 65   href="lang_dele
2030: 74 65 2e 68 74 6d 6c 22 3e 44 45 4c 45 54 45 3c  te.html">DELETE<
2040: 2f 61 3e 20 62 75 74 20 6e 6f 74 20 3c 61 20 68  /a> but not <a h
2050: 72 65 66 3d 22 6c 61 6e 67 5f 75 70 64 61 74 65  ref="lang_update
2060: 2e 68 74 6d 6c 22 3e 55 50 44 41 54 45 3c 2f 61  .html">UPDATE</a
2070: 3e 2e 20 20 4f 72 20 73 6f 6d 65 20 76 69 72 74  >.  Or some virt
2080: 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
2090: 65 6e 74 61 74 69 6f 6e 73 0a 6d 69 67 68 74 20  entations.might 
20a0: 6c 69 6d 69 74 20 74 68 65 20 6b 69 6e 64 73 20  limit the kinds 
20b0: 6f 66 20 55 50 44 41 54 45 73 20 74 68 61 74 20  of UPDATEs that 
20c0: 63 61 6e 20 62 65 20 6d 61 64 65 2e 0a 0a 3c 2f  can be made...</
20d0: 70 3e 3c 70 3e 41 20 76 69 72 74 75 61 6c 20 74  p><p>A virtual t
20e0: 61 62 6c 65 20 6d 69 67 68 74 20 72 65 70 72 65  able might repre
20f0: 73 65 6e 74 20 61 6e 20 69 6e 2d 6d 65 6d 6f 72  sent an in-memor
2100: 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  y data structure
2110: 73 2e 20 0a 4f 72 20 69 74 20 6d 69 67 68 74 20  s. .Or it might 
2120: 72 65 70 72 65 73 65 6e 74 20 61 20 76 69 65 77  represent a view
2130: 20 6f 66 20 64 61 74 61 20 6f 6e 20 64 69 73 6b   of data on disk
2140: 20 74 68 61 74 20 69 73 20 6e 6f 74 20 69 6e 20   that is not in 
2150: 74 68 65 0a 53 51 4c 69 74 65 20 66 6f 72 6d 61  the.SQLite forma
2160: 74 2e 20 4f 72 20 74 68 65 20 61 70 70 6c 69 63  t. Or the applic
2170: 61 74 69 6f 6e 20 6d 69 67 68 74 20 63 6f 6d 70  ation might comp
2180: 75 74 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  ute the content 
2190: 6f 66 20 74 68 65 20 0a 76 69 72 74 75 61 6c 20  of the .virtual 
21a0: 74 61 62 6c 65 20 6f 6e 20 64 65 6d 61 6e 64 2e  table on demand.
21b0: 0a 0a 3c 2f 70 3e 3c 70 3e 48 65 72 65 20 61 72  ..</p><p>Here ar
21c0: 65 20 73 6f 6d 65 20 65 78 69 73 74 69 6e 67 20  e some existing 
21d0: 61 6e 64 20 70 6f 73 74 75 6c 61 74 65 64 20 75  and postulated u
21e0: 73 65 73 20 66 6f 72 20 76 69 72 74 75 61 6c 20  ses for virtual 
21f0: 74 61 62 6c 65 73 3a 0a 0a 3c 2f 70 3e 3c 75 6c  tables:..</p><ul
2200: 3e 0a 3c 6c 69 3e 20 41 20 3c 61 20 68 72 65 66  >.<li> A <a href
2210: 3d 22 66 74 73 33 2e 68 74 6d 6c 22 3e 66 75 6c  ="fts3.html">ful
2220: 6c 2d 74 65 78 74 20 73 65 61 72 63 68 3c 2f 61  l-text search</a
2230: 3e 20 69 6e 74 65 72 66 61 63 65 0a 3c 2f 6c 69  > interface.</li
2240: 3e 3c 6c 69 3e 20 53 70 61 74 69 61 6c 20 69 6e  ><li> Spatial in
2250: 64 69 63 65 73 20 75 73 69 6e 67 20 3c 61 20 68  dices using <a h
2260: 72 65 66 3d 22 72 74 72 65 65 2e 68 74 6d 6c 22  ref="rtree.html"
2270: 3e 52 2d 54 72 65 65 73 3c 2f 61 3e 0a 3c 2f 6c  >R-Trees</a>.</l
2280: 69 3e 3c 6c 69 3e 20 49 6e 74 72 6f 73 70 65 63  i><li> Introspec
2290: 74 20 74 68 65 20 64 69 73 6b 20 63 6f 6e 74 65  t the disk conte
22a0: 6e 74 20 6f 66 20 61 6e 20 53 51 4c 69 74 65 20  nt of an SQLite 
22b0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 20 20  database file.  
22c0: 20 20 20 28 74 68 65 20 3c 61 20 68 72 65 66 3d     (the <a href=
22d0: 22 64 62 73 74 61 74 2e 68 74 6d 6c 22 3e 64 62  "dbstat.html">db
22e0: 73 74 61 74 20 76 69 72 74 75 61 6c 20 74 61 62  stat virtual tab
22f0: 6c 65 3c 2f 61 3e 29 0a 3c 2f 6c 69 3e 3c 6c 69  le</a>).</li><li
2300: 3e 20 52 65 61 64 20 61 6e 64 2f 6f 72 20 77 72  > Read and/or wr
2310: 69 74 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  ite the content 
2320: 6f 66 20 61 20 63 6f 6d 6d 61 2d 73 65 70 61 72  of a comma-separ
2330: 61 74 65 64 20 76 61 6c 75 65 20 28 43 53 56 29  ated value (CSV)
2340: 0a 20 20 20 20 20 66 69 6c 65 0a 3c 2f 6c 69 3e  .     file.</li>
2350: 3c 6c 69 3e 20 41 63 63 65 73 73 20 74 68 65 20  <li> Access the 
2360: 66 69 6c 65 73 79 73 74 65 6d 20 6f 66 20 74 68  filesystem of th
2370: 65 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 20  e host computer 
2380: 61 73 20 69 66 20 69 74 20 77 65 72 65 20 61 20  as if it were a 
2390: 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 0a 3c  database table.<
23a0: 2f 6c 69 3e 3c 6c 69 3e 20 45 6e 61 62 6c 69 6e  /li><li> Enablin
23b0: 67 20 53 51 4c 20 6d 61 6e 69 70 75 6c 61 74 69  g SQL manipulati
23c0: 6f 6e 20 6f 66 20 64 61 74 61 20 69 6e 20 73 74  on of data in st
23d0: 61 74 69 73 74 69 63 73 20 70 61 63 6b 61 67 65  atistics package
23e0: 73 20 6c 69 6b 65 20 52 0a 3c 2f 6c 69 3e 3c 2f  s like R.</li></
23f0: 75 6c 3e 0a 0a 3c 70 3e 53 65 65 20 74 68 65 20  ul>..<p>See the 
2400: 3c 61 20 68 72 65 66 3d 22 76 74 61 62 6c 69 73  <a href="vtablis
2410: 74 2e 68 74 6d 6c 22 3e 6c 69 73 74 20 6f 66 20  t.html">list of 
2420: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 3c 2f  virtual tables</
2430: 61 3e 20 70 61 67 65 20 66 6f 72 20 61 20 6c 6f  a> page for a lo
2440: 6e 67 65 72 20 6c 69 73 74 20 6f 66 20 61 63 74  nger list of act
2450: 75 61 6c 0a 76 69 72 74 75 61 6c 20 74 61 62 6c  ual.virtual tabl
2460: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2470: 73 2e 0a 0a 0a 3c 2f 70 3e 3c 68 32 20 69 64 3d  s....</p><h2 id=
2480: 22 75 73 61 67 65 22 3e 3c 73 70 61 6e 3e 31 2e  "usage"><span>1.
2490: 31 2e 20 3c 2f 73 70 61 6e 3e 55 73 61 67 65 3c  1. </span>Usage<
24a0: 2f 68 32 3e 0a 0a 3c 70 3e 41 20 76 69 72 74 75  /h2>..<p>A virtu
24b0: 61 6c 20 74 61 62 6c 65 20 69 73 20 63 72 65 61  al table is crea
24c0: 74 65 64 20 75 73 69 6e 67 20 61 20 3c 61 20 68  ted using a <a h
24d0: 72 65 66 3d 22 6c 61 6e 67 5f 63 72 65 61 74 65  ref="lang_create
24e0: 76 74 61 62 2e 68 74 6d 6c 22 3e 43 52 45 41 54  vtab.html">CREAT
24f0: 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45 3c  E VIRTUAL TABLE<
2500: 2f 61 3e 20 73 74 61 74 65 6d 65 6e 74 2e 0a 0a  /a> statement...
2510: 3c 70 3e 3c 62 3e 3c 61 20 68 72 65 66 3d 22 73  <p><b><a href="s
2520: 79 6e 74 61 78 2f 63 72 65 61 74 65 2d 76 69 72  yntax/create-vir
2530: 74 75 61 6c 2d 74 61 62 6c 65 2d 73 74 6d 74 2e  tual-table-stmt.
2540: 68 74 6d 6c 22 3e 63 72 65 61 74 65 2d 76 69 72  html">create-vir
2550: 74 75 61 6c 2d 74 61 62 6c 65 2d 73 74 6d 74 3a  tual-table-stmt:
2560: 3c 2f 61 3e 3c 2f 62 3e 0a 3c 62 75 74 74 6f 6e  </a></b>.<button
2570: 20 69 64 3d 27 78 31 35 37 35 27 20 6f 6e 63 6c   id='x1575' oncl
2580: 69 63 6b 3d 27 68 69 64 65 6f 72 73 68 6f 77 28  ick='hideorshow(
2590: 22 78 31 35 37 35 22 2c 22 78 31 35 37 36 22 29  "x1575","x1576")
25a0: 27 3e 68 69 64 65 3c 2f 62 75 74 74 6f 6e 3e 3c  '>hide</button><
25b0: 2f 70 3e 0a 20 3c 64 69 76 20 69 64 3d 27 78 31  /p>. <div id='x1
25c0: 35 37 36 27 20 63 6c 61 73 73 3d 27 69 6d 67 63  576' class='imgc
25d0: 6f 6e 74 61 69 6e 65 72 27 3e 0a 20 3c 69 6d 67  ontainer'>. <img
25e0: 20 61 6c 74 3d 22 73 79 6e 74 61 78 20 64 69 61   alt="syntax dia
25f0: 67 72 61 6d 20 63 72 65 61 74 65 2d 76 69 72 74  gram create-virt
2600: 75 61 6c 2d 74 61 62 6c 65 2d 73 74 6d 74 22 20  ual-table-stmt" 
2610: 73 72 63 3d 22 69 6d 61 67 65 73 2f 73 79 6e 74  src="images/synt
2620: 61 78 2f 63 72 65 61 74 65 2d 76 69 72 74 75 61  ax/create-virtua
2630: 6c 2d 74 61 62 6c 65 2d 73 74 6d 74 2e 67 69 66  l-table-stmt.gif
2640: 22 20 2f 3e 0a 3c 2f 64 69 76 3e 0a 0a 0a 3c 2f  " />.</div>...</
2650: 70 3e 3c 70 3e 54 68 65 20 43 52 45 41 54 45 20  p><p>The CREATE 
2660: 56 49 52 54 55 41 4c 20 54 41 42 4c 45 20 73 74  VIRTUAL TABLE st
2670: 61 74 65 6d 65 6e 74 20 63 72 65 61 74 65 73 20  atement creates 
2680: 61 20 6e 65 77 20 74 61 62 6c 65 0a 63 61 6c 6c  a new table.call
2690: 65 64 20 3c 73 70 61 6e 20 63 6c 61 73 73 3d 27  ed <span class='
26a0: 79 79 74 65 72 6d 27 3e 74 61 62 6c 65 2d 6e 61  yyterm'>table-na
26b0: 6d 65 3c 2f 73 70 61 6e 3e 20 64 65 72 69 76 65  me</span> derive
26c0: 64 20 66 72 6f 6d 20 74 68 65 20 63 6c 61 73 73  d from the class
26d0: 0a 63 6c 61 73 73 20 3c 73 70 61 6e 20 63 6c 61  .class <span cla
26e0: 73 73 3d 27 79 79 74 65 72 6d 27 3e 6d 6f 64 75  ss='yyterm'>modu
26f0: 6c 65 2d 6e 61 6d 65 3c 2f 73 70 61 6e 3e 2e 20  le-name</span>. 
2700: 20 54 68 65 20 3c 73 70 61 6e 20 63 6c 61 73 73   The <span class
2710: 3d 27 79 79 74 65 72 6d 27 3e 6d 6f 64 75 6c 65  ='yyterm'>module
2720: 2d 6e 61 6d 65 3c 2f 73 70 61 6e 3e 0a 69 73 20  -name</span>.is 
2730: 74 68 65 20 6e 61 6d 65 20 74 68 61 74 20 69 73  the name that is
2740: 20 72 65 67 69 73 74 65 72 65 64 20 66 6f 72 20   registered for 
2750: 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
2760: 65 20 62 79 0a 74 68 65 20 3c 61 20 68 72 65 66  e by.the <a href
2770: 3d 22 63 33 72 65 66 2f 63 72 65 61 74 65 5f 6d  ="c3ref/create_m
2780: 6f 64 75 6c 65 2e 68 74 6d 6c 22 3e 73 71 6c 69  odule.html">sqli
2790: 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
27a0: 65 28 29 3c 2f 61 3e 20 69 6e 74 65 72 66 61 63  e()</a> interfac
27b0: 65 2e 0a 0a 3c 2f 70 3e 3c 64 69 76 20 63 6c 61  e...</p><div cla
27c0: 73 73 3d 22 63 6f 64 65 62 6c 6f 63 6b 22 3e 3c  ss="codeblock"><
27d0: 70 72 65 3e 43 52 45 41 54 45 20 56 49 52 54 55  pre>CREATE VIRTU
27e0: 41 4c 20 54 41 42 4c 45 20 74 61 62 6c 65 6e 61  AL TABLE tablena
27f0: 6d 65 20 55 53 49 4e 47 20 6d 6f 64 75 6c 65 6e  me USING modulen
2800: 61 6d 65 3b 0a 3c 2f 70 72 65 3e 3c 2f 64 69 76  ame;.</pre></div
2810: 3e 0a 0a 3c 70 3e 4f 6e 65 20 63 61 6e 20 61 6c  >..<p>One can al
2820: 73 6f 20 70 72 6f 76 69 64 65 20 63 6f 6d 6d 61  so provide comma
2830: 2d 73 65 70 61 72 61 74 65 64 20 61 72 67 75 6d  -separated argum
2840: 65 6e 74 73 20 74 6f 20 74 68 65 20 6d 6f 64 75  ents to the modu
2850: 6c 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 0a 74 68  le following .th
2860: 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 3a 0a 0a  e module name:..
2870: 3c 2f 70 3e 3c 64 69 76 20 63 6c 61 73 73 3d 22  </p><div class="
2880: 63 6f 64 65 62 6c 6f 63 6b 22 3e 3c 70 72 65 3e  codeblock"><pre>
2890: 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54  CREATE VIRTUAL T
28a0: 41 42 4c 45 20 74 61 62 6c 65 6e 61 6d 65 20 55  ABLE tablename U
28b0: 53 49 4e 47 20 6d 6f 64 75 6c 65 6e 61 6d 65 28  SING modulename(
28c0: 61 72 67 31 2c 20 61 72 67 32 2c 20 2e 2e 2e 29  arg1, arg2, ...)
28d0: 3b 0a 3c 2f 70 72 65 3e 3c 2f 64 69 76 3e 0a 0a  ;.</pre></div>..
28e0: 3c 70 3e 54 68 65 20 66 6f 72 6d 61 74 20 6f 66  <p>The format of
28f0: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 73 20 74   the arguments t
2900: 6f 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 73 20  o the module is 
2910: 76 65 72 79 20 67 65 6e 65 72 61 6c 2e 20 45 61  very general. Ea
2920: 63 68 20 0a 3c 73 70 61 6e 20 63 6c 61 73 73 3d  ch .<span class=
2930: 27 79 79 74 65 72 6d 27 3e 6d 6f 64 75 6c 65 2d  'yyterm'>module-
2940: 61 72 67 75 6d 65 6e 74 3c 2f 73 70 61 6e 3e 0a  argument</span>.
2950: 6d 61 79 20 63 6f 6e 74 61 69 6e 20 6b 65 79 77  may contain keyw
2960: 6f 72 64 73 2c 20 73 74 72 69 6e 67 20 6c 69 74  ords, string lit
2970: 65 72 61 6c 73 2c 20 69 64 65 6e 74 69 66 69 65  erals, identifie
2980: 72 73 2c 20 6e 75 6d 62 65 72 73 2c 20 61 6e 64  rs, numbers, and
2990: 20 0a 70 75 6e 63 74 75 61 74 69 6f 6e 2e 20 45   .punctuation. E
29a0: 61 63 68 20 3c 73 70 61 6e 20 63 6c 61 73 73 3d  ach <span class=
29b0: 27 79 79 74 65 72 6d 27 3e 6d 6f 64 75 6c 65 2d  'yyterm'>module-
29c0: 61 72 67 75 6d 65 6e 74 3c 2f 73 70 61 6e 3e 20  argument</span> 
29d0: 69 73 20 70 61 73 73 65 64 20 61 73 20 0a 77 72  is passed as .wr
29e0: 69 74 74 65 6e 20 28 61 73 20 74 65 78 74 29 20  itten (as text) 
29f0: 69 6e 74 6f 20 74 68 65 0a 3c 61 20 68 72 65 66  into the.<a href
2a00: 3d 22 76 74 61 62 2e 68 74 6d 6c 23 78 63 72 65  ="vtab.html#xcre
2a10: 61 74 65 22 3e 63 6f 6e 73 74 72 75 63 74 6f 72  ate">constructor
2a20: 20 6d 65 74 68 6f 64 3c 2f 61 3e 20 6f 66 20 74   method</a> of t
2a30: 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
2a40: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2a50: 0a 77 68 65 6e 20 74 68 65 20 76 69 72 74 75 61  .when the virtua
2a60: 6c 20 0a 74 61 62 6c 65 20 69 73 20 63 72 65 61  l .table is crea
2a70: 74 65 64 20 61 6e 64 20 74 68 61 74 20 63 6f 6e  ted and that con
2a80: 73 74 72 75 63 74 6f 72 20 69 73 20 72 65 73 70  structor is resp
2a90: 6f 6e 73 69 62 6c 65 20 66 6f 72 20 70 61 72 73  onsible for pars
2aa0: 69 6e 67 20 61 6e 64 20 0a 69 6e 74 65 72 70 72  ing and .interpr
2ab0: 65 74 69 6e 67 20 74 68 65 20 61 72 67 75 6d 65  eting the argume
2ac0: 6e 74 73 2e 20 54 68 65 20 61 72 67 75 6d 65 6e  nts. The argumen
2ad0: 74 20 73 79 6e 74 61 78 20 69 73 20 73 75 66 66  t syntax is suff
2ae0: 69 63 69 65 6e 74 6c 79 20 67 65 6e 65 72 61 6c  iciently general
2af0: 20 0a 74 68 61 74 20 61 20 76 69 72 74 75 61 6c   .that a virtual
2b00: 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
2b10: 61 74 69 6f 6e 20 63 61 6e 2c 20 69 66 20 69 74  ation can, if it
2b20: 20 77 61 6e 74 73 20 74 6f 2c 20 69 6e 74 65 72   wants to, inter
2b30: 70 72 65 74 20 69 74 73 0a 61 72 67 75 6d 65 6e  pret its.argumen
2b40: 74 73 20 61 73 20 3c 61 20 68 72 65 66 3d 22 6c  ts as <a href="l
2b50: 61 6e 67 5f 63 72 65 61 74 65 74 61 62 6c 65 2e  ang_createtable.
2b60: 68 74 6d 6c 23 74 61 62 6c 65 63 6f 6c 64 65 66  html#tablecoldef
2b70: 22 3e 63 6f 6c 75 6d 6e 20 64 65 66 69 6e 69 74  ">column definit
2b80: 69 6f 6e 73 3c 2f 61 3e 20 69 6e 20 61 6e 20 6f  ions</a> in an o
2b90: 72 64 69 6e 61 72 79 20 3c 61 20 68 72 65 66 3d  rdinary <a href=
2ba0: 22 6c 61 6e 67 5f 63 72 65 61 74 65 74 61 62 6c  "lang_createtabl
2bb0: 65 2e 68 74 6d 6c 22 3e 43 52 45 41 54 45 20 54  e.html">CREATE T
2bc0: 41 42 4c 45 3c 2f 61 3e 20 73 74 61 74 65 6d 65  ABLE</a> stateme
2bd0: 6e 74 2e 20 0a 54 68 65 20 69 6d 70 6c 65 6d 65  nt. .The impleme
2be0: 6e 74 61 74 69 6f 6e 20 63 6f 75 6c 64 20 61 6c  ntation could al
2bf0: 73 6f 20 69 6d 70 6f 73 65 20 73 6f 6d 65 20 6f  so impose some o
2c00: 74 68 65 72 20 69 6e 74 65 72 70 72 65 74 61 74  ther interpretat
2c10: 69 6f 6e 20 6f 6e 20 74 68 65 20 0a 61 72 67 75  ion on the .argu
2c20: 6d 65 6e 74 73 2e 0a 0a 3c 2f 70 3e 3c 70 3e 4f  ments...</p><p>O
2c30: 6e 63 65 20 61 20 76 69 72 74 75 61 6c 20 74 61  nce a virtual ta
2c40: 62 6c 65 20 68 61 73 20 62 65 65 6e 20 63 72 65  ble has been cre
2c50: 61 74 65 64 2c 20 69 74 20 63 61 6e 20 62 65 20  ated, it can be 
2c60: 75 73 65 64 20 6c 69 6b 65 20 61 6e 79 20 6f 74  used like any ot
2c70: 68 65 72 20 0a 74 61 62 6c 65 20 77 69 74 68 20  her .table with 
2c80: 74 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20 6e  the exceptions n
2c90: 6f 74 65 64 20 61 62 6f 76 65 20 61 6e 64 20 69  oted above and i
2ca0: 6d 70 6f 73 65 64 20 62 79 20 73 70 65 63 69 66  mposed by specif
2cb0: 69 63 20 76 69 72 74 75 61 6c 0a 74 61 62 6c 65  ic virtual.table
2cc0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2cd0: 2e 20 41 20 76 69 72 74 75 61 6c 20 74 61 62 6c  . A virtual tabl
2ce0: 65 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 75  e is destroyed u
2cf0: 73 69 6e 67 20 74 68 65 20 6f 72 64 69 6e 61 72  sing the ordinar
2d00: 79 0a 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f  y.<a href="lang_
2d10: 64 72 6f 70 74 61 62 6c 65 2e 68 74 6d 6c 22 3e  droptable.html">
2d20: 44 52 4f 50 20 54 41 42 4c 45 3c 2f 61 3e 20 73  DROP TABLE</a> s
2d30: 79 6e 74 61 78 2e 0a 0a 3c 2f 70 3e 3c 68 33 20  yntax...</p><h3 
2d40: 69 64 3d 22 74 65 6d 70 6f 72 61 72 79 5f 76 69  id="temporary_vi
2d50: 72 74 75 61 6c 5f 74 61 62 6c 65 73 22 3e 3c 73  rtual_tables"><s
2d60: 70 61 6e 3e 31 2e 31 2e 31 2e 20 3c 2f 73 70 61  pan>1.1.1. </spa
2d70: 6e 3e 54 65 6d 70 6f 72 61 72 79 20 76 69 72 74  n>Temporary virt
2d80: 75 61 6c 20 74 61 62 6c 65 73 3c 2f 68 33 3e 0a  ual tables</h3>.
2d90: 0a 3c 70 3e 54 68 65 72 65 20 69 73 20 6e 6f 20  .<p>There is no 
2da0: 22 43 52 45 41 54 45 20 54 45 4d 50 20 56 49 52  "CREATE TEMP VIR
2db0: 54 55 41 4c 20 54 41 42 4c 45 22 20 73 74 61 74  TUAL TABLE" stat
2dc0: 65 6d 65 6e 74 2e 20 20 54 6f 20 63 72 65 61 74  ement.  To creat
2dd0: 65 20 61 0a 74 65 6d 70 6f 72 61 72 79 20 76 69  e a.temporary vi
2de0: 72 74 75 61 6c 20 74 61 62 6c 65 2c 20 61 64 64  rtual table, add
2df0: 20 74 68 65 20 22 74 65 6d 70 22 20 73 63 68 65   the "temp" sche
2e00: 6d 61 0a 62 65 66 6f 72 65 20 74 68 65 20 76 69  ma.before the vi
2e10: 72 74 75 61 6c 20 74 61 62 6c 65 20 6e 61 6d 65  rtual table name
2e20: 2e 0a 0a 3c 2f 70 3e 3c 64 69 76 20 63 6c 61 73  ...</p><div clas
2e30: 73 3d 22 63 6f 64 65 62 6c 6f 63 6b 22 3e 3c 70  s="codeblock"><p
2e40: 72 65 3e 43 52 45 41 54 45 20 56 49 52 54 55 41  re>CREATE VIRTUA
2e50: 4c 20 54 41 42 4c 45 20 3c 62 3e 74 65 6d 70 2e  L TABLE <b>temp.
2e60: 3c 2f 62 3e 74 61 62 6c 65 6e 61 6d 65 20 55 53  </b>tablename US
2e70: 49 4e 47 20 6d 6f 64 75 6c 65 28 61 72 67 31 2c  ING module(arg1,
2e80: 20 2e 2e 2e 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 64   ...);.</pre></d
2e90: 69 76 3e 0a 0a 3c 61 20 6e 61 6d 65 3d 22 65 70  iv>..<a name="ep
2ea0: 6f 76 74 61 62 22 3e 3c 2f 61 3e 0a 0a 3c 68 33  ovtab"></a>..<h3
2eb0: 20 69 64 3d 22 65 70 6f 6e 79 6d 6f 75 73 5f 76   id="eponymous_v
2ec0: 69 72 74 75 61 6c 5f 74 61 62 6c 65 73 22 3e 3c  irtual_tables"><
2ed0: 73 70 61 6e 3e 31 2e 31 2e 32 2e 20 3c 2f 73 70  span>1.1.2. </sp
2ee0: 61 6e 3e 45 70 6f 6e 79 6d 6f 75 73 20 76 69 72  an>Eponymous vir
2ef0: 74 75 61 6c 20 74 61 62 6c 65 73 3c 2f 68 33 3e  tual tables</h3>
2f00: 0a 0a 3c 70 3e 53 6f 6d 65 20 76 69 72 74 75 61  ..<p>Some virtua
2f10: 6c 20 74 61 62 6c 65 73 20 65 78 69 73 74 20 61  l tables exist a
2f20: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20  utomatically in 
2f30: 74 68 65 20 22 6d 61 69 6e 22 20 73 63 68 65 6d  the "main" schem
2f40: 61 20 6f 66 0a 65 76 65 72 79 20 64 61 74 61 62  a of.every datab
2f50: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
2f60: 6e 20 77 68 69 63 68 20 74 68 65 69 72 0a 6d 6f  n which their.mo
2f70: 64 75 6c 65 20 69 73 20 72 65 67 69 73 74 65 72  dule is register
2f80: 65 64 2c 20 65 76 65 6e 20 77 69 74 68 6f 75 74  ed, even without
2f90: 20 61 20 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67   a <a href="lang
2fa0: 5f 63 72 65 61 74 65 76 74 61 62 2e 68 74 6d 6c  _createvtab.html
2fb0: 22 3e 43 52 45 41 54 45 20 56 49 52 54 55 41 4c  ">CREATE VIRTUAL
2fc0: 20 54 41 42 4c 45 3c 2f 61 3e 20 73 74 61 74 65   TABLE</a> state
2fd0: 6d 65 6e 74 2e 0a 53 75 63 68 20 76 69 72 74 75  ment..Such virtu
2fe0: 61 6c 20 74 61 62 6c 65 73 20 61 72 65 20 63 61  al tables are ca
2ff0: 6c 6c 65 64 20 22 65 70 6f 6e 79 6d 6f 75 73 20  lled "eponymous 
3000: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 22 2e  virtual tables".
3010: 0a 54 6f 20 75 73 65 20 61 6e 20 65 70 6f 6e 79  .To use an epony
3020: 6d 6f 75 73 20 76 69 72 74 75 61 6c 20 74 61 62  mous virtual tab
3030: 6c 65 2c 20 73 69 6d 70 6c 79 20 75 73 65 20 74  le, simply use t
3040: 68 65 20 0a 6d 6f 64 75 6c 65 20 6e 61 6d 65 20  he .module name 
3050: 61 73 20 69 66 20 69 74 20 77 65 72 65 20 61 20  as if it were a 
3060: 74 61 62 6c 65 2e 0a 45 70 6f 6e 79 6d 6f 75 73  table..Eponymous
3070: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   virtual tables 
3080: 65 78 69 73 74 20 69 6e 20 74 68 65 20 22 6d 61  exist in the "ma
3090: 69 6e 22 20 73 63 68 65 6d 61 20 6f 6e 6c 79 2c  in" schema only,
30a0: 20 73 6f 20 74 68 65 79 20 77 69 6c 6c 0a 6e 6f   so they will.no
30b0: 74 20 77 6f 72 6b 20 69 66 20 70 72 65 66 69 78  t work if prefix
30c0: 65 64 20 77 69 74 68 20 61 20 64 69 66 66 65 72  ed with a differ
30d0: 65 6e 74 20 73 63 68 65 6d 61 20 6e 61 6d 65 2e  ent schema name.
30e0: 0a 0a 3c 2f 70 3e 3c 70 3e 41 6e 20 65 78 61 6d  ..</p><p>An exam
30f0: 70 6c 65 20 6f 66 20 61 6e 20 65 70 6f 6e 79 6d  ple of an eponym
3100: 6f 75 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c  ous virtual tabl
3110: 65 20 69 73 20 74 68 65 20 3c 61 20 68 72 65 66  e is the <a href
3120: 3d 22 64 62 73 74 61 74 2e 68 74 6d 6c 22 3e 64  ="dbstat.html">d
3130: 62 73 74 61 74 20 76 69 72 74 75 61 6c 20 74 61  bstat virtual ta
3140: 62 6c 65 3c 2f 61 3e 2e 0a 54 6f 20 75 73 65 20  ble</a>..To use 
3150: 74 68 65 20 64 62 73 74 61 74 20 76 69 72 74 75  the dbstat virtu
3160: 61 6c 20 74 61 62 6c 65 20 61 73 20 61 6e 20 65  al table as an e
3170: 70 6f 6e 79 6d 6f 75 73 20 76 69 72 74 75 61 6c  ponymous virtual
3180: 20 74 61 62 6c 65 2c 20 0a 73 69 6d 70 6c 79 20   table, .simply 
3190: 71 75 65 72 79 20 61 67 61 69 6e 73 74 20 74 68  query against th
31a0: 65 20 22 64 62 73 74 61 74 22 0a 6d 6f 64 75 6c  e "dbstat".modul
31b0: 65 20 6e 61 6d 65 2c 20 61 73 20 69 66 20 69 74  e name, as if it
31c0: 20 77 65 72 65 20 61 6e 20 6f 72 64 69 6e 61 72   were an ordinar
31d0: 79 20 74 61 62 6c 65 2e 20 20 28 4e 6f 74 65 20  y table.  (Note 
31e0: 74 68 61 74 20 53 51 4c 69 74 65 0a 6d 75 73 74  that SQLite.must
31f0: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   be compiled wit
3200: 68 20 74 68 65 20 3c 61 20 68 72 65 66 3d 22 63  h the <a href="c
3210: 6f 6d 70 69 6c 65 2e 68 74 6d 6c 23 65 6e 61 62  ompile.html#enab
3220: 6c 65 5f 64 62 73 74 61 74 5f 76 74 61 62 22 3e  le_dbstat_vtab">
3230: 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 44 42  SQLITE_ENABLE_DB
3240: 53 54 41 54 5f 56 54 41 42 3c 2f 61 3e 20 6f 70  STAT_VTAB</a> op
3250: 74 69 6f 6e 20 74 6f 20 69 6e 63 6c 75 64 65 0a  tion to include.
3260: 74 68 65 20 64 62 73 74 61 74 20 76 69 72 74 75  the dbstat virtu
3270: 61 6c 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20  al table in the 
3280: 62 75 69 6c 64 2e 29 0a 0a 3c 2f 70 3e 3c 64 69  build.)..</p><di
3290: 76 20 63 6c 61 73 73 3d 22 63 6f 64 65 62 6c 6f  v class="codeblo
32a0: 63 6b 22 3e 3c 70 72 65 3e 53 45 4c 45 43 54 20  ck"><pre>SELECT 
32b0: 2a 20 46 52 4f 4d 20 64 62 73 74 61 74 3b 0a 3c  * FROM dbstat;.<
32c0: 2f 70 72 65 3e 3c 2f 64 69 76 3e 0a 0a 3c 70 3e  /pre></div>..<p>
32d0: 41 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  A virtual table 
32e0: 69 73 20 65 70 6f 6e 79 6d 6f 75 73 20 69 66 20  is eponymous if 
32f0: 69 74 73 20 3c 61 20 68 72 65 66 3d 22 76 74 61  its <a href="vta
3300: 62 2e 68 74 6d 6c 23 78 63 72 65 61 74 65 22 3e  b.html#xcreate">
3310: 78 43 72 65 61 74 65 3c 2f 61 3e 20 6d 65 74 68  xCreate</a> meth
3320: 6f 64 20 69 73 20 74 68 65 20 65 78 61 63 74 20  od is the exact 
3330: 73 61 6d 65 0a 66 75 6e 63 74 69 6f 6e 20 61 73  same.function as
3340: 20 74 68 65 20 3c 61 20 68 72 65 66 3d 22 76 74   the <a href="vt
3350: 61 62 2e 68 74 6d 6c 23 78 63 6f 6e 6e 65 63 74  ab.html#xconnect
3360: 22 3e 78 43 6f 6e 6e 65 63 74 3c 2f 61 3e 20 6d  ">xConnect</a> m
3370: 65 74 68 6f 64 2c 20 6f 72 20 69 66 20 74 68 65  ethod, or if the
3380: 20 3c 61 20 68 72 65 66 3d 22 76 74 61 62 2e 68   <a href="vtab.h
3390: 74 6d 6c 23 78 63 72 65 61 74 65 22 3e 78 43 72  tml#xcreate">xCr
33a0: 65 61 74 65 3c 2f 61 3e 20 6d 65 74 68 6f 64 20  eate</a> method 
33b0: 69 73 20 4e 55 4c 4c 2e 0a 54 68 65 20 3c 61 20  is NULL..The <a 
33c0: 68 72 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23  href="vtab.html#
33d0: 78 63 72 65 61 74 65 22 3e 78 43 72 65 61 74 65  xcreate">xCreate
33e0: 3c 2f 61 3e 20 6d 65 74 68 6f 64 20 69 73 20 63  </a> method is c
33f0: 61 6c 6c 65 64 20 77 68 65 6e 20 61 20 76 69 72  alled when a vir
3400: 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20 66 69  tual table is fi
3410: 72 73 74 20 63 72 65 61 74 65 64 0a 75 73 69 6e  rst created.usin
3420: 67 20 74 68 65 20 3c 61 20 68 72 65 66 3d 22 6c  g the <a href="l
3430: 61 6e 67 5f 63 72 65 61 74 65 76 74 61 62 2e 68  ang_createvtab.h
3440: 74 6d 6c 22 3e 43 52 45 41 54 45 20 56 49 52 54  tml">CREATE VIRT
3450: 55 41 4c 20 54 41 42 4c 45 3c 2f 61 3e 20 73 74  UAL TABLE</a> st
3460: 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 3c 61  atement.  The <a
3470: 20 68 72 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c   href="vtab.html
3480: 23 78 63 6f 6e 6e 65 63 74 22 3e 78 43 6f 6e 6e  #xconnect">xConn
3490: 65 63 74 3c 2f 61 3e 20 6d 65 74 68 6f 64 20 0a  ect</a> method .
34a0: 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  is invoked whene
34b0: 76 65 72 0a 61 20 64 61 74 61 62 61 73 65 20 63  ver.a database c
34c0: 6f 6e 6e 65 63 74 69 6f 6e 20 61 74 74 61 63 68  onnection attach
34d0: 65 73 20 74 6f 20 6f 72 20 72 65 70 61 72 73 65  es to or reparse
34e0: 73 20 61 20 73 63 68 65 6d 61 2e 20 57 68 65 6e  s a schema. When
34f0: 20 74 68 65 73 65 20 74 77 6f 20 6d 65 74 68 6f   these two metho
3500: 64 73 0a 61 72 65 20 74 68 65 20 73 61 6d 65 2c  ds.are the same,
3510: 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
3520: 74 68 61 74 20 74 68 65 20 76 69 72 74 75 61 6c  that the virtual
3530: 20 74 61 62 6c 65 20 68 61 73 20 6e 6f 20 70 65   table has no pe
3540: 72 73 69 73 74 65 6e 74 0a 73 74 61 74 65 20 74  rsistent.state t
3550: 68 61 74 20 6e 65 65 64 73 20 74 6f 20 62 65 20  hat needs to be 
3560: 63 72 65 61 74 65 64 20 61 6e 64 20 64 65 73 74  created and dest
3570: 72 6f 79 65 64 2e 0a 0a 3c 61 20 6e 61 6d 65 3d  royed...<a name=
3580: 22 65 70 6f 6f 6e 6c 79 76 74 61 62 22 3e 3c 2f  "epoonlyvtab"></
3590: 61 3e 0a 0a 3c 2f 70 3e 3c 68 33 20 69 64 3d 22  a>..</p><h3 id="
35a0: 65 70 6f 6e 79 6d 6f 75 73 5f 6f 6e 6c 79 5f 76  eponymous_only_v
35b0: 69 72 74 75 61 6c 5f 74 61 62 6c 65 73 22 3e 3c  irtual_tables"><
35c0: 73 70 61 6e 3e 31 2e 31 2e 33 2e 20 3c 2f 73 70  span>1.1.3. </sp
35d0: 61 6e 3e 45 70 6f 6e 79 6d 6f 75 73 2d 6f 6e 6c  an>Eponymous-onl
35e0: 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  y virtual tables
35f0: 3c 2f 68 33 3e 0a 3c 70 3e 49 66 20 74 68 65 20  </h3>.<p>If the 
3600: 3c 61 20 68 72 65 66 3d 22 76 74 61 62 2e 68 74  <a href="vtab.ht
3610: 6d 6c 23 78 63 72 65 61 74 65 22 3e 78 43 72 65  ml#xcreate">xCre
3620: 61 74 65 3c 2f 61 3e 20 6d 65 74 68 6f 64 20 69  ate</a> method i
3630: 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a 3c 61 20  s NULL, then.<a 
3640: 68 72 65 66 3d 22 6c 61 6e 67 5f 63 72 65 61 74  href="lang_creat
3650: 65 76 74 61 62 2e 68 74 6d 6c 22 3e 43 52 45 41  evtab.html">CREA
3660: 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c 45  TE VIRTUAL TABLE
3670: 3c 2f 61 3e 20 73 74 61 74 65 6d 65 6e 74 73 20  </a> statements 
3680: 61 72 65 20 70 72 6f 68 69 62 69 74 65 64 20 66  are prohibited f
3690: 6f 72 20 74 68 61 74 20 76 69 72 74 75 61 6c 20  or that virtual 
36a0: 74 61 62 6c 65 2c 0a 61 6e 64 20 74 68 65 20 76  table,.and the v
36b0: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20  irtual table is 
36c0: 61 6e 20 22 65 70 6f 6e 79 6d 6f 75 73 2d 6f 6e  an "eponymous-on
36d0: 6c 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ly virtual table
36e0: 22 2e 0a 45 70 6f 6e 79 6d 6f 75 73 2d 6f 6e 6c  "..Eponymous-onl
36f0: 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  y virtual tables
3700: 20 61 72 65 20 75 73 65 66 75 6c 20 61 73 20 0a   are useful as .
3710: 3c 61 20 68 72 65 66 3d 22 76 74 61 62 2e 68 74  <a href="vtab.ht
3720: 6d 6c 23 74 61 62 66 75 6e 63 32 22 3e 74 61 62  ml#tabfunc2">tab
3730: 6c 65 2d 76 61 6c 75 65 64 20 66 75 6e 63 74 69  le-valued functi
3740: 6f 6e 73 3c 2f 61 3e 2e 0a 0a 3c 2f 70 3e 3c 70  ons</a>...</p><p
3750: 3e 0a 4e 6f 74 65 20 74 68 61 74 20 70 72 69 6f  >.Note that prio
3760: 72 20 74 6f 20 3c 61 20 68 72 65 66 3d 22 72 65  r to <a href="re
3770: 6c 65 61 73 65 6c 6f 67 2f 33 5f 39 5f 30 2e 68  leaselog/3_9_0.h
3780: 74 6d 6c 22 3e 76 65 72 73 69 6f 6e 20 33 2e 39  tml">version 3.9
3790: 2e 30 3c 2f 61 3e 20 28 32 30 31 35 2d 31 30 2d  .0</a> (2015-10-
37a0: 31 34 29 2c 20 0a 53 51 4c 69 74 65 20 64 69 64  14), .SQLite did
37b0: 20 6e 6f 74 20 63 68 65 63 6b 20 74 68 65 20 78   not check the x
37c0: 43 72 65 61 74 65 20 6d 65 74 68 6f 64 0a 66 6f  Create method.fo
37d0: 72 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 69 6e  r NULL before in
37e0: 76 6f 6b 69 6e 67 20 69 74 2e 20 20 53 6f 20 69  voking it.  So i
37f0: 66 20 61 6e 20 65 70 6f 6e 79 6d 6f 75 73 2d 6f  f an eponymous-o
3800: 6e 6c 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c  nly virtual tabl
3810: 65 20 69 73 0a 72 65 67 69 73 74 65 72 65 64 20  e is.registered 
3820: 77 69 74 68 20 53 51 4c 69 74 65 20 3c 61 20 68  with SQLite <a h
3830: 72 65 66 3d 22 72 65 6c 65 61 73 65 6c 6f 67 2f  ref="releaselog/
3840: 33 5f 38 5f 31 31 5f 31 2e 68 74 6d 6c 22 3e 76  3_8_11_1.html">v
3850: 65 72 73 69 6f 6e 20 33 2e 38 2e 31 31 2e 31 3c  ersion 3.8.11.1<
3860: 2f 61 3e 20 28 32 30 31 35 2d 30 37 2d 32 39 29  /a> (2015-07-29)
3870: 0a 6f 72 20 65 61 72 6c 69 65 72 20 61 6e 64 20  .or earlier and 
3880: 61 20 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f  a <a href="lang_
3890: 63 72 65 61 74 65 76 74 61 62 2e 68 74 6d 6c 22  createvtab.html"
38a0: 3e 43 52 45 41 54 45 20 56 49 52 54 55 41 4c 20  >CREATE VIRTUAL 
38b0: 54 41 42 4c 45 3c 2f 61 3e 0a 63 6f 6d 6d 61 6e  TABLE</a>.comman
38c0: 64 20 69 73 20 61 74 74 65 6d 70 74 65 64 20 61  d is attempted a
38d0: 67 61 69 6e 73 74 20 74 68 61 74 20 76 69 72 74  gainst that virt
38e0: 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
38f0: 2c 20 61 20 6a 75 6d 70 20 74 6f 20 61 20 4e 55  , a jump to a NU
3900: 4c 4c 0a 70 6f 69 6e 74 65 72 20 77 69 6c 6c 20  LL.pointer will 
3910: 6f 63 63 75 72 2c 20 72 65 73 75 6c 74 69 6e 67  occur, resulting
3920: 20 69 6e 20 61 20 63 72 61 73 68 2e 0a 0a 3c 2f   in a crash...</
3930: 70 3e 3c 68 32 20 69 64 3d 22 69 6d 70 6c 65 6d  p><h2 id="implem
3940: 65 6e 74 61 74 69 6f 6e 22 3e 3c 73 70 61 6e 3e  entation"><span>
3950: 31 2e 32 2e 20 3c 2f 73 70 61 6e 3e 49 6d 70 6c  1.2. </span>Impl
3960: 65 6d 65 6e 74 61 74 69 6f 6e 3c 2f 68 32 3e 0a  ementation</h2>.
3970: 0a 3c 70 3e 53 65 76 65 72 61 6c 20 6e 65 77 20  .<p>Several new 
3980: 43 2d 6c 65 76 65 6c 20 6f 62 6a 65 63 74 73 20  C-level objects 
3990: 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20  are used by the 
39a0: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  virtual table im
39b0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 3a 0a 0a 3c  plementation:..<
39c0: 2f 70 3e 3c 64 69 76 20 63 6c 61 73 73 3d 22 63  /p><div class="c
39d0: 6f 64 65 62 6c 6f 63 6b 22 3e 3c 70 72 65 3e 74  odeblock"><pre>t
39e0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
39f0: 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74  lite3_vtab sqlit
3a00: 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66  e3_vtab;.typedef
3a10: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
3a20: 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74  index_info sqlit
3a30: 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74  e3_index_info;.t
3a40: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
3a50: 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
3a60: 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  r sqlite3_vtab_c
3a70: 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73  ursor;.typedef s
3a80: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f  truct sqlite3_mo
3a90: 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64  dule sqlite3_mod
3aa0: 75 6c 65 3b 0a 3c 2f 70 72 65 3e 3c 2f 64 69 76  ule;.</pre></div
3ab0: 3e 0a 0a 3c 70 3e 54 68 65 20 3c 61 20 68 72 65  >..<p>The <a hre
3ac0: 66 3d 22 63 33 72 65 66 2f 6d 6f 64 75 6c 65 2e  f="c3ref/module.
3ad0: 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 6d 6f  html">sqlite3_mo
3ae0: 64 75 6c 65 3c 2f 61 3e 20 73 74 72 75 63 74 75  dule</a> structu
3af0: 72 65 20 64 65 66 69 6e 65 73 20 61 20 6d 6f 64  re defines a mod
3b00: 75 6c 65 20 6f 62 6a 65 63 74 20 75 73 65 64 20  ule object used 
3b10: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 61 20 76  to implement.a v
3b20: 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 54 68  irtual table. Th
3b30: 69 6e 6b 20 6f 66 20 61 20 6d 6f 64 75 6c 65 20  ink of a module 
3b40: 61 73 20 61 20 63 6c 61 73 73 20 66 72 6f 6d 20  as a class from 
3b50: 77 68 69 63 68 20 6f 6e 65 20 63 61 6e 20 0a 63  which one can .c
3b60: 6f 6e 73 74 72 75 63 74 20 6d 75 6c 74 69 70 6c  onstruct multipl
3b70: 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  e virtual tables
3b80: 20 68 61 76 69 6e 67 20 73 69 6d 69 6c 61 72 20   having similar 
3b90: 70 72 6f 70 65 72 74 69 65 73 2e 20 46 6f 72 20  properties. For 
3ba0: 65 78 61 6d 70 6c 65 2c 0a 6f 6e 65 20 6d 69 67  example,.one mig
3bb0: 68 74 20 68 61 76 65 20 61 20 6d 6f 64 75 6c 65  ht have a module
3bc0: 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 72   that provides r
3bd0: 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 20  ead-only access 
3be0: 74 6f 20 0a 63 6f 6d 6d 61 2d 73 65 70 61 72 61  to .comma-separa
3bf0: 74 65 64 2d 76 61 6c 75 65 20 28 43 53 56 29 20  ted-value (CSV) 
3c00: 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 20 54  files on disk. T
3c10: 68 61 74 20 6f 6e 65 20 6d 6f 64 75 6c 65 20 63  hat one module c
3c20: 61 6e 20 74 68 65 6e 20 62 65 0a 75 73 65 64 20  an then be.used 
3c30: 74 6f 20 63 72 65 61 74 65 20 73 65 76 65 72 61  to create severa
3c40: 6c 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  l virtual tables
3c50: 20 77 68 65 72 65 20 65 61 63 68 20 76 69 72 74   where each virt
3c60: 75 61 6c 20 74 61 62 6c 65 20 72 65 66 65 72 73  ual table refers
3c70: 0a 74 6f 20 61 20 64 69 66 66 65 72 65 6e 74 20  .to a different 
3c80: 43 53 56 20 66 69 6c 65 2e 0a 0a 3c 2f 70 3e 3c  CSV file...</p><
3c90: 70 3e 54 68 65 20 6d 6f 64 75 6c 65 20 73 74 72  p>The module str
3ca0: 75 63 74 75 72 65 20 63 6f 6e 74 61 69 6e 73 20  ucture contains 
3cb0: 6d 65 74 68 6f 64 73 20 74 68 61 74 20 61 72 65  methods that are
3cc0: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
3cd0: 74 65 20 74 6f 0a 70 65 72 66 6f 72 6d 20 76 61  te to.perform va
3ce0: 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 20 6f 6e  rious actions on
3cf0: 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
3d00: 6c 65 20 73 75 63 68 20 61 73 20 63 72 65 61 74  le such as creat
3d10: 69 6e 67 20 6e 65 77 0a 69 6e 73 74 61 6e 63 65  ing new.instance
3d20: 73 20 6f 66 20 61 20 76 69 72 74 75 61 6c 20 74  s of a virtual t
3d30: 61 62 6c 65 20 6f 72 20 64 65 73 74 72 6f 79 69  able or destroyi
3d40: 6e 67 20 6f 6c 64 20 6f 6e 65 73 2c 20 72 65 61  ng old ones, rea
3d50: 64 69 6e 67 20 61 6e 64 0a 77 72 69 74 69 6e 67  ding and.writing
3d60: 20 64 61 74 61 2c 20 73 65 61 72 63 68 69 6e 67   data, searching
3d70: 20 66 6f 72 20 61 6e 64 20 64 65 6c 65 74 69 6e   for and deletin
3d80: 67 2c 20 75 70 64 61 74 69 6e 67 2c 20 6f 72 20  g, updating, or 
3d90: 69 6e 73 65 72 74 69 6e 67 20 72 6f 77 73 2e 20  inserting rows. 
3da0: 0a 54 68 65 20 6d 6f 64 75 6c 65 20 73 74 72 75  .The module stru
3db0: 63 74 75 72 65 20 69 73 20 65 78 70 6c 61 69 6e  cture is explain
3dc0: 65 64 20 69 6e 20 6d 6f 72 65 20 64 65 74 61 69  ed in more detai
3dd0: 6c 20 62 65 6c 6f 77 2e 0a 0a 3c 2f 70 3e 3c 70  l below...</p><p
3de0: 3e 45 61 63 68 20 76 69 72 74 75 61 6c 20 74 61  >Each virtual ta
3df0: 62 6c 65 20 69 6e 73 74 61 6e 63 65 20 69 73 20  ble instance is 
3e00: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
3e10: 6e 20 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66  n <a href="c3ref
3e20: 2f 76 74 61 62 2e 68 74 6d 6c 22 3e 73 71 6c 69  /vtab.html">sqli
3e30: 74 65 33 5f 76 74 61 62 3c 2f 61 3e 20 73 74 72  te3_vtab</a> str
3e40: 75 63 74 75 72 65 2e 20 0a 54 68 65 20 73 71 6c  ucture. .The sql
3e50: 69 74 65 33 5f 76 74 61 62 20 73 74 72 75 63 74  ite3_vtab struct
3e60: 75 72 65 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 74  ure looks like t
3e70: 68 69 73 3a 0a 0a 3c 2f 70 3e 3c 64 69 76 20 63  his:..</p><div c
3e80: 6c 61 73 73 3d 22 63 6f 64 65 62 6c 6f 63 6b 22  lass="codeblock"
3e90: 3e 3c 70 72 65 3e 73 74 72 75 63 74 20 73 71 6c  ><pre>struct sql
3ea0: 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f  ite3_vtab {.  co
3eb0: 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  nst sqlite3_modu
3ec0: 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 0a 20 20 69  le *pModule;.  i
3ed0: 6e 74 20 6e 52 65 66 3b 0a 20 20 63 68 61 72 20  nt nRef;.  char 
3ee0: 2a 7a 45 72 72 4d 73 67 3b 0a 7d 3b 0a 3c 2f 70  *zErrMsg;.};.</p
3ef0: 72 65 3e 3c 2f 64 69 76 3e 0a 0a 3c 70 3e 56 69  re></div>..<p>Vi
3f00: 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
3f10: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
3f20: 20 6e 6f 72 6d 61 6c 6c 79 20 73 75 62 63 6c 61   normally subcla
3f30: 73 73 20 74 68 69 73 20 73 74 72 75 63 74 75 72  ss this structur
3f40: 65 20 0a 74 6f 20 61 64 64 20 61 64 64 69 74 69  e .to add additi
3f50: 6f 6e 61 6c 20 70 72 69 76 61 74 65 20 61 6e 64  onal private and
3f60: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2d   implementation-
3f70: 73 70 65 63 69 66 69 63 20 66 69 65 6c 64 73 2e  specific fields.
3f80: 20 0a 54 68 65 20 6e 52 65 66 20 66 69 65 6c 64   .The nRef field
3f90: 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
3fa0: 6c 6c 79 20 62 79 20 74 68 65 20 53 51 4c 69 74  lly by the SQLit
3fb0: 65 20 63 6f 72 65 20 61 6e 64 20 73 68 6f 75 6c  e core and shoul
3fc0: 64 20 6e 6f 74 20 0a 62 65 20 61 6c 74 65 72 65  d not .be altere
3fd0: 64 20 62 79 20 74 68 65 20 76 69 72 74 75 61 6c  d by the virtual
3fe0: 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
3ff0: 61 74 69 6f 6e 2e 20 54 68 65 20 76 69 72 74 75  ation. The virtu
4000: 61 6c 20 74 61 62 6c 65 20 0a 69 6d 70 6c 65 6d  al table .implem
4010: 65 6e 74 61 74 69 6f 6e 20 6d 61 79 20 70 61 73  entation may pas
4020: 73 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  s error message 
4030: 74 65 78 74 20 74 6f 20 74 68 65 20 63 6f 72 65  text to the core
4040: 20 62 79 20 70 75 74 74 69 6e 67 20 0a 61 6e 20   by putting .an 
4050: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
4060: 72 69 6e 67 20 69 6e 20 7a 45 72 72 4d 73 67 2e  ring in zErrMsg.
4070: 0a 53 70 61 63 65 20 74 6f 20 68 6f 6c 64 20 74  .Space to hold t
4080: 68 69 73 20 65 72 72 6f 72 20 6d 65 73 73 61 67  his error messag
4090: 65 20 73 74 72 69 6e 67 20 6d 75 73 74 20 62 65  e string must be
40a0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
40b0: 6e 0a 53 51 4c 69 74 65 20 6d 65 6d 6f 72 79 20  n.SQLite memory 
40c0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74  allocation funct
40d0: 69 6f 6e 20 73 75 63 68 20 61 73 20 3c 61 20 68  ion such as <a h
40e0: 72 65 66 3d 22 63 33 72 65 66 2f 6d 70 72 69 6e  ref="c3ref/mprin
40f0: 74 66 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33  tf.html">sqlite3
4100: 5f 6d 70 72 69 6e 74 66 28 29 3c 2f 61 3e 20 6f  _mprintf()</a> o
4110: 72 0a 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66  r.<a href="c3ref
4120: 2f 66 72 65 65 2e 68 74 6d 6c 22 3e 73 71 6c 69  /free.html">sqli
4130: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 3c 2f 61 3e  te3_malloc()</a>
4140: 2e 0a 50 72 69 6f 72 20 74 6f 20 61 73 73 69 67  ..Prior to assig
4150: 6e 69 6e 67 20 61 20 6e 65 77 20 76 61 6c 75 65  ning a new value
4160: 20 74 6f 20 7a 45 72 72 4d 73 67 2c 20 74 68 65   to zErrMsg, the
4170: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 0a   virtual table .
4180: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
4190: 75 73 74 20 66 72 65 65 20 61 6e 79 20 70 72 65  ust free any pre
41a0: 65 78 69 73 74 69 6e 67 20 63 6f 6e 74 65 6e 74  existing content
41b0: 20 6f 66 20 7a 45 72 72 4d 73 67 20 75 73 69 6e   of zErrMsg usin
41c0: 67 20 0a 3c 61 20 68 72 65 66 3d 22 63 33 72 65  g .<a href="c3re
41d0: 66 2f 66 72 65 65 2e 68 74 6d 6c 22 3e 73 71 6c  f/free.html">sql
41e0: 69 74 65 33 5f 66 72 65 65 28 29 3c 2f 61 3e 2e  ite3_free()</a>.
41f0: 20 46 61 69 6c 75 72 65 20 74 6f 20 64 6f 20 74   Failure to do t
4200: 68 69 73 20 77 69 6c 6c 20 72 65 73 75 6c 74 20  his will result 
4210: 69 6e 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b  in a memory leak
4220: 2e 20 0a 54 68 65 20 53 51 4c 69 74 65 20 63 6f  . .The SQLite co
4230: 72 65 20 77 69 6c 6c 20 66 72 65 65 20 61 6e 64  re will free and
4240: 20 7a 65 72 6f 20 74 68 65 20 63 6f 6e 74 65 6e   zero the conten
4250: 74 20 6f 66 20 7a 45 72 72 4d 73 67 20 77 68 65  t of zErrMsg whe
4260: 6e 20 69 74 20 0a 64 65 6c 69 76 65 72 73 20 74  n it .delivers t
4270: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
4280: 20 74 65 78 74 20 74 6f 20 74 68 65 20 63 6c 69   text to the cli
4290: 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ent application 
42a0: 6f 72 20 77 68 65 6e 20 0a 69 74 20 64 65 73 74  or when .it dest
42b0: 72 6f 79 73 20 74 68 65 20 76 69 72 74 75 61 6c  roys the virtual
42c0: 20 74 61 62 6c 65 2e 20 54 68 65 20 76 69 72 74   table. The virt
42d0: 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
42e0: 65 6e 74 61 74 69 6f 6e 20 6f 6e 6c 79 20 0a 6e  entation only .n
42f0: 65 65 64 73 20 74 6f 20 77 6f 72 72 79 20 61 62  eeds to worry ab
4300: 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20  out freeing the 
4310: 7a 45 72 72 4d 73 67 20 63 6f 6e 74 65 6e 74 20  zErrMsg content 
4320: 77 68 65 6e 20 69 74 20 6f 76 65 72 77 72 69 74  when it overwrit
4330: 65 73 20 0a 74 68 65 20 63 6f 6e 74 65 6e 74 20  es .the content 
4340: 77 69 74 68 20 61 20 6e 65 77 2c 20 64 69 66 66  with a new, diff
4350: 65 72 65 6e 74 20 65 72 72 6f 72 20 6d 65 73 73  erent error mess
4360: 61 67 65 2e 0a 0a 3c 2f 70 3e 3c 70 3e 54 68 65  age...</p><p>The
4370: 20 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f   <a href="c3ref/
4380: 76 74 61 62 5f 63 75 72 73 6f 72 2e 68 74 6d 6c  vtab_cursor.html
4390: 22 3e 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  ">sqlite3_vtab_c
43a0: 75 72 73 6f 72 3c 2f 61 3e 20 73 74 72 75 63 74  ursor</a> struct
43b0: 75 72 65 20 72 65 70 72 65 73 65 6e 74 73 20 61  ure represents a
43c0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 70   pointer to a sp
43d0: 65 63 69 66 69 63 0a 72 6f 77 20 6f 66 20 61 20  ecific.row of a 
43e0: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 54  virtual table. T
43f0: 68 69 73 20 69 73 20 77 68 61 74 20 61 6e 20 73  his is what an s
4400: 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
4410: 6f 72 20 6c 6f 6f 6b 73 20 6c 69 6b 65 3a 0a 0a  or looks like:..
4420: 3c 2f 70 3e 3c 64 69 76 20 63 6c 61 73 73 3d 22  </p><div class="
4430: 63 6f 64 65 62 6c 6f 63 6b 22 3e 3c 70 72 65 3e  codeblock"><pre>
4440: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
4450: 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73  tab_cursor {.  s
4460: 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
4470: 61 62 3b 0a 7d 3b 0a 3c 2f 70 72 65 3e 3c 2f 64  ab;.};.</pre></d
4480: 69 76 3e 0a 0a 3c 70 3e 4f 6e 63 65 20 61 67 61  iv>..<p>Once aga
4490: 69 6e 2c 20 70 72 61 63 74 69 63 61 6c 20 69 6d  in, practical im
44a0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
44b0: 6c 6c 20 6c 69 6b 65 6c 79 20 73 75 62 63 6c 61  ll likely subcla
44c0: 73 73 20 74 68 69 73 20 0a 73 74 72 75 63 74 75  ss this .structu
44d0: 72 65 20 74 6f 20 61 64 64 20 61 64 64 69 74 69  re to add additi
44e0: 6f 6e 61 6c 20 70 72 69 76 61 74 65 20 66 69 65  onal private fie
44f0: 6c 64 73 2e 0a 0a 3c 2f 70 3e 3c 70 3e 54 68 65  lds...</p><p>The
4500: 20 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f   <a href="c3ref/
4510: 69 6e 64 65 78 5f 69 6e 66 6f 2e 68 74 6d 6c 22  index_info.html"
4520: 3e 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69  >sqlite3_index_i
4530: 6e 66 6f 3c 2f 61 3e 20 73 74 72 75 63 74 75 72  nfo</a> structur
4540: 65 20 69 73 20 75 73 65 64 20 74 6f 20 70 61 73  e is used to pas
4550: 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e  s information in
4560: 74 6f 0a 61 6e 64 20 6f 75 74 20 6f 66 20 74 68  to.and out of th
4570: 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74  e xBestIndex met
4580: 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  hod of the modul
4590: 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  e that implement
45a0: 73 20 61 20 0a 76 69 72 74 75 61 6c 20 74 61 62  s a .virtual tab
45b0: 6c 65 2e 0a 0a 3c 2f 70 3e 3c 70 3e 42 65 66 6f  le...</p><p>Befo
45c0: 72 65 20 61 20 3c 61 20 68 72 65 66 3d 22 6c 61  re a <a href="la
45d0: 6e 67 5f 63 72 65 61 74 65 76 74 61 62 2e 68 74  ng_createvtab.ht
45e0: 6d 6c 22 3e 43 52 45 41 54 45 20 56 49 52 54 55  ml">CREATE VIRTU
45f0: 41 4c 20 54 41 42 4c 45 3c 2f 61 3e 20 73 74 61  AL TABLE</a> sta
4600: 74 65 6d 65 6e 74 20 63 61 6e 20 62 65 20 72 75  tement can be ru
4610: 6e 2c 20 74 68 65 20 6d 6f 64 75 6c 65 20 0a 73  n, the module .s
4620: 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 61 74  pecified in that
4630: 20 73 74 61 74 65 6d 65 6e 74 20 6d 75 73 74 20   statement must 
4640: 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69  be registered wi
4650: 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  th the database 
4660: 0a 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54 68 69  .connection. Thi
4670: 73 20 69 73 20 61 63 63 6f 6d 70 6c 69 73 68 65  s is accomplishe
4680: 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 6f  d using either o
4690: 66 20 74 68 65 20 3c 61 20 68 72 65 66 3d 22 63  f the <a href="c
46a0: 33 72 65 66 2f 63 72 65 61 74 65 5f 6d 6f 64 75  3ref/create_modu
46b0: 6c 65 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33  le.html">sqlite3
46c0: 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29  _create_module()
46d0: 3c 2f 61 3e 0a 6f 72 20 3c 61 20 68 72 65 66 3d  </a>.or <a href=
46e0: 22 63 33 72 65 66 2f 63 72 65 61 74 65 5f 6d 6f  "c3ref/create_mo
46f0: 64 75 6c 65 2e 68 74 6d 6c 22 3e 73 71 6c 69 74  dule.html">sqlit
4700: 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
4710: 5f 76 32 28 29 3c 2f 61 3e 20 69 6e 74 65 72 66  _v2()</a> interf
4720: 61 63 65 73 3a 0a 0a 3c 2f 70 3e 3c 64 69 76 20  aces:..</p><div 
4730: 63 6c 61 73 73 3d 22 63 6f 64 65 62 6c 6f 63 6b  class="codeblock
4740: 22 3e 3c 70 72 65 3e 69 6e 74 20 73 71 6c 69 74  "><pre>int sqlit
4750: 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
4760: 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
4770: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4780: 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74  * SQLite connect
4790: 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20  ion to register 
47a0: 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20  module with */. 
47b0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
47c0: 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  me,         /* N
47d0: 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  ame of the modul
47e0: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c  e */.  const sql
47f0: 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c 20 20  ite3_module *,  
4800: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
4810: 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
4820: 20 76 6f 69 64 20 2a 20 20 20 20 20 20 20 20 20   void *         
4830: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
4840: 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78  lient data for x
4850: 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20  Create/xConnect 
4860: 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
4870: 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f  3_create_module_
4880: 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
4890: 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
48a0: 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65   /* SQLite conne
48b0: 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65  ction to registe
48c0: 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f  r module with */
48d0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
48e0: 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a  Name,         /*
48f0: 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64   Name of the mod
4900: 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73  ule */.  const s
4910: 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 2c  qlite3_module *,
4920: 20 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66      /* Methods f
4930: 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  or the module */
4940: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
4950: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
4960: 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72   Client data for
4970: 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63   xCreate/xConnec
4980: 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65  t */.  void(*xDe
4990: 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 20  stroy)(void*)   
49a0: 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61    /* Client data
49b0: 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63   destructor func
49c0: 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 3c 2f 70 72 65  tion */.);.</pre
49d0: 3e 3c 2f 64 69 76 3e 0a 0a 3c 70 3e 54 68 65 20  ></div>..<p>The 
49e0: 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f 63  <a href="c3ref/c
49f0: 72 65 61 74 65 5f 6d 6f 64 75 6c 65 2e 68 74 6d  reate_module.htm
4a00: 6c 22 3e 73 71 6c 69 74 65 33 5f 63 72 65 61 74  l">sqlite3_creat
4a10: 65 5f 6d 6f 64 75 6c 65 28 29 3c 2f 61 3e 20 61  e_module()</a> a
4a20: 6e 64 20 3c 61 20 68 72 65 66 3d 22 63 33 72 65  nd <a href="c3re
4a30: 66 2f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 2e  f/create_module.
4a40: 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 63 72  html">sqlite3_cr
4a50: 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29  eate_module_v2()
4a60: 3c 2f 61 3e 0a 72 6f 75 74 69 6e 65 73 20 61 73  </a>.routines as
4a70: 73 6f 63 69 61 74 65 73 20 61 20 6d 6f 64 75 6c  sociates a modul
4a80: 65 20 6e 61 6d 65 20 77 69 74 68 20 0a 61 6e 20  e name with .an 
4a90: 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f 6d  <a href="c3ref/m
4aa0: 6f 64 75 6c 65 2e 68 74 6d 6c 22 3e 73 71 6c 69  odule.html">sqli
4ab0: 74 65 33 5f 6d 6f 64 75 6c 65 3c 2f 61 3e 20 73  te3_module</a> s
4ac0: 74 72 75 63 74 75 72 65 20 61 6e 64 20 61 20 73  tructure and a s
4ad0: 65 70 61 72 61 74 65 20 63 6c 69 65 6e 74 20 64  eparate client d
4ae0: 61 74 61 20 74 68 61 74 20 69 73 20 73 70 65 63  ata that is spec
4af0: 69 66 69 63 20 0a 74 6f 20 65 61 63 68 20 6d 6f  ific .to each mo
4b00: 64 75 6c 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20  dule.  The only 
4b10: 64 69 66 66 65 72 65 6e 63 65 20 62 65 74 77 65  difference betwe
4b20: 65 6e 20 74 68 65 20 74 77 6f 20 63 72 65 61 74  en the two creat
4b30: 65 5f 6d 6f 64 75 6c 65 20 6d 65 74 68 6f 64 73  e_module methods
4b40: 0a 69 73 20 74 68 61 74 20 74 68 65 20 5f 76 32  .is that the _v2
4b50: 20 6d 65 74 68 6f 64 20 69 6e 63 6c 75 64 65 73   method includes
4b60: 20 61 6e 20 65 78 74 72 61 20 70 61 72 61 6d 65   an extra parame
4b70: 74 65 72 20 74 68 61 74 20 73 70 65 63 69 66 69  ter that specifi
4b80: 65 73 20 61 0a 64 65 73 74 72 75 63 74 6f 72 20  es a.destructor 
4b90: 66 6f 72 20 63 6c 69 65 6e 74 20 64 61 74 61 20  for client data 
4ba0: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 6d 6f  pointer.  The mo
4bb0: 64 75 6c 65 20 73 74 72 75 63 74 75 72 65 20 69  dule structure i
4bc0: 73 20 77 68 61 74 20 64 65 66 69 6e 65 73 0a 74  s what defines.t
4bd0: 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 61  he behavior of a
4be0: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20   virtual table. 
4bf0: 20 54 68 65 20 6d 6f 64 75 6c 65 20 73 74 72 75   The module stru
4c00: 63 74 75 72 65 20 6c 6f 6f 6b 73 20 6c 69 6b 65  cture looks like
4c10: 20 74 68 69 73 3a 0a 0a 3c 2f 70 3e 3c 64 69 76   this:..</p><div
4c20: 20 63 6c 61 73 73 3d 22 63 6f 64 65 62 6c 6f 63   class="codebloc
4c30: 6b 22 3e 3c 70 72 65 3e 0a 73 74 72 75 63 74 20  k"><pre>.struct 
4c40: 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b  sqlite3_module {
4c50: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
4c60: 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65  .  int (*xCreate
4c70: 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  )(sqlite3*, void
4c80: 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20   *pAux,.        
4c90: 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
4ca0: 20 63 68 61 72 20 2a 2a 61 72 67 76 2c 0a 20 20   char **argv,.  
4cb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c               sql
4cc0: 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54  ite3_vtab **ppVT
4cd0: 61 62 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  ab,.            
4ce0: 20 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 29     char **pzErr)
4cf0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65  ;.  int (*xConne
4d00: 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ct)(sqlite3*, vo
4d10: 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20  id *pAux,.      
4d20: 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
4d30: 63 2c 20 63 68 61 72 20 2a 2a 61 72 67 76 2c 0a  c, char **argv,.
4d40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73                 s
4d50: 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70  qlite3_vtab **pp
4d60: 56 54 61 62 2c 0a 20 20 20 20 20 20 20 20 20 20  VTab,.          
4d70: 20 20 20 20 20 63 68 61 72 20 2a 2a 70 7a 45 72       char **pzEr
4d80: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 73  r);.  int (*xBes
4d90: 74 49 6e 64 65 78 29 28 73 71 6c 69 74 65 33 5f  tIndex)(sqlite3_
4da0: 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c  vtab *pVTab, sql
4db0: 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a  ite3_index_info*
4dc0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69 73 63  );.  int (*xDisc
4dd0: 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 5f  onnect)(sqlite3_
4de0: 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
4df0: 69 6e 74 20 28 2a 78 44 65 73 74 72 6f 79 29 28  int (*xDestroy)(
4e00: 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
4e10: 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f  Tab);.  int (*xO
4e20: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  pen)(sqlite3_vta
4e30: 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65  b *pVTab, sqlite
4e40: 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a  3_vtab_cursor **
4e50: 70 70 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74  ppCursor);.  int
4e60: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
4e70: 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29  e3_vtab_cursor*)
4e80: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 74 65  ;.  int (*xFilte
4e90: 72 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  r)(sqlite3_vtab_
4ea0: 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78  cursor*, int idx
4eb0: 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  Num, const char 
4ec0: 2a 69 64 78 53 74 72 2c 0a 20 20 20 20 20 20 20  *idxStr,.       
4ed0: 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
4ee0: 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  c, sqlite3_value
4ef0: 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74 20   **argv);.  int 
4f00: 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 65 33  (*xNext)(sqlite3
4f10: 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a  _vtab_cursor*);.
4f20: 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71    int (*xEof)(sq
4f30: 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
4f40: 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  r*);.  int (*xCo
4f50: 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  lumn)(sqlite3_vt
4f60: 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69  ab_cursor*, sqli
4f70: 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
4f80: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77  t);.  int (*xRow
4f90: 69 64 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  id)(sqlite3_vtab
4fa0: 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65  _cursor*, sqlite
4fb0: 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3b  _int64 *pRowid);
4fc0: 0a 20 20 69 6e 74 20 28 2a 78 55 70 64 61 74 65  .  int (*xUpdate
4fd0: 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
4fe0: 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76  , int, sqlite3_v
4ff0: 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 5f  alue **, sqlite_
5000: 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20  int64 *);.  int 
5010: 28 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65  (*xBegin)(sqlite
5020: 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
5030: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
5040: 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
5050: 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  ab);.  int (*xCo
5060: 6d 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74  mmit)(sqlite3_vt
5070: 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
5080: 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73  t (*xRollback)(s
5090: 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
50a0: 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  ab);.  int (*xFi
50b0: 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69  ndFunction)(sqli
50c0: 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c  te3_vtab *pVtab,
50d0: 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74   int nArg, const
50e0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20   char *zName,.  
50f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5100: 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e     void (**pxFun
5110: 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
5120: 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
5130: 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20  value**),.      
5140: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
5150: 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20  oid **ppArg);.  
5160: 69 6e 74 20 28 2a 52 65 6e 61 6d 65 29 28 73 71  int (*Rename)(sq
5170: 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61  lite3_vtab *pVta
5180: 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  b, const char *z
5190: 4e 65 77 29 3b 0a 20 20 2f 2a 20 54 68 65 20 6d  New);.  /* The m
51a0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
51b0: 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66   in version 1 of
51c0: 20 74 68 65 20 73 71 6c 69 74 65 5f 6d 6f 64 75   the sqlite_modu
51d0: 6c 65 20 6f 62 6a 65 63 74 2e 20 54 68 6f 73 65  le object. Those
51e0: 20 0a 20 20 2a 2a 20 62 65 6c 6f 77 20 61 72 65   .  ** below are
51f0: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 61   for version 2 a
5200: 6e 64 20 67 72 65 61 74 65 72 2e 20 2a 2f 0a 20  nd greater. */. 
5210: 20 69 6e 74 20 28 2a 78 53 61 76 65 70 6f 69 6e   int (*xSavepoin
5220: 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  t)(sqlite3_vtab 
5230: 2a 70 56 54 61 62 2c 20 69 6e 74 29 3b 0a 20 20  *pVTab, int);.  
5240: 69 6e 74 20 28 2a 78 52 65 6c 65 61 73 65 29 28  int (*xRelease)(
5250: 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
5260: 54 61 62 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  Tab, int);.  int
5270: 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 54 6f 29 28   (*xRollbackTo)(
5280: 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
5290: 54 61 62 2c 20 69 6e 74 29 3b 0a 7d 3b 0a 3c 2f  Tab, int);.};.</
52a0: 70 72 65 3e 3c 2f 64 69 76 3e 0a 0a 3c 70 3e 54  pre></div>..<p>T
52b0: 68 65 20 6d 6f 64 75 6c 65 20 73 74 72 75 63 74  he module struct
52c0: 75 72 65 20 64 65 66 69 6e 65 73 20 61 6c 6c 20  ure defines all 
52d0: 6f 66 20 74 68 65 20 6d 65 74 68 6f 64 73 20 66  of the methods f
52e0: 6f 72 20 65 61 63 68 20 76 69 72 74 75 61 6c 20  or each virtual 
52f0: 0a 74 61 62 6c 65 20 6f 62 6a 65 63 74 2e 20 54  .table object. T
5300: 68 65 20 6d 6f 64 75 6c 65 20 73 74 72 75 63 74  he module struct
5310: 75 72 65 20 61 6c 73 6f 20 63 6f 6e 74 61 69 6e  ure also contain
5320: 73 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  s the iVersion f
5330: 69 65 6c 64 20 77 68 69 63 68 0a 64 65 66 69 6e  ield which.defin
5340: 65 73 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  es the particula
5350: 72 20 65 64 69 74 69 6f 6e 20 6f 66 20 74 68 65  r edition of the
5360: 20 6d 6f 64 75 6c 65 20 74 61 62 6c 65 20 73 74   module table st
5370: 72 75 63 74 75 72 65 2e 20 43 75 72 72 65 6e 74  ructure. Current
5380: 6c 79 2c 20 0a 69 56 65 72 73 69 6f 6e 20 69 73  ly, .iVersion is
5390: 20 61 6c 77 61 79 73 20 31 2c 20 62 75 74 20 69   always 1, but i
53a0: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
53b0: 73 20 6f 66 20 53 51 4c 69 74 65 20 74 68 65 20  s of SQLite the 
53c0: 6d 6f 64 75 6c 65 20 73 74 72 75 63 74 75 72 65  module structure
53d0: 20 0a 64 65 66 69 6e 69 74 69 6f 6e 20 6d 69 67   .definition mig
53e0: 68 74 20 62 65 20 65 78 74 65 6e 64 65 64 20 77  ht be extended w
53f0: 69 74 68 20 61 64 64 69 74 69 6f 6e 61 6c 20 6d  ith additional m
5400: 65 74 68 6f 64 73 20 61 6e 64 20 69 6e 20 74 68  ethods and in th
5410: 61 74 20 63 61 73 65 20 0a 74 68 65 20 69 56 65  at case .the iVe
5420: 72 73 69 6f 6e 20 76 61 6c 75 65 20 77 69 6c 6c  rsion value will
5430: 20 62 65 20 69 6e 63 72 65 61 73 65 64 2e 0a 0a   be increased...
5440: 3c 2f 70 3e 3c 70 3e 54 68 65 20 72 65 73 74 20  </p><p>The rest 
5450: 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 73 74  of the module st
5460: 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73  ructure consists
5470: 20 6f 66 20 6d 65 74 68 6f 64 73 20 75 73 65 64   of methods used
5480: 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 76 61   to implement.va
5490: 72 69 6f 75 73 20 66 65 61 74 75 72 65 73 20 6f  rious features o
54a0: 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  f the virtual ta
54b0: 62 6c 65 2e 20 44 65 74 61 69 6c 73 20 6f 6e 20  ble. Details on 
54c0: 77 68 61 74 20 65 61 63 68 20 6f 66 20 74 68 65  what each of the
54d0: 73 65 20 0a 6d 65 74 68 6f 64 73 20 64 6f 20 61  se .methods do a
54e0: 72 65 20 70 72 6f 76 69 64 65 64 20 69 6e 20 74  re provided in t
54f0: 68 65 20 73 65 71 75 65 6c 2e 0a 0a 3c 2f 70 3e  he sequel...</p>
5500: 3c 68 32 20 69 64 3d 22 76 69 72 74 75 61 6c 5f  <h2 id="virtual_
5510: 74 61 62 6c 65 73 5f 61 6e 64 5f 73 68 61 72 65  tables_and_share
5520: 64 5f 63 61 63 68 65 22 3e 3c 73 70 61 6e 3e 31  d_cache"><span>1
5530: 2e 33 2e 20 3c 2f 73 70 61 6e 3e 56 69 72 74 75  .3. </span>Virtu
5540: 61 6c 20 54 61 62 6c 65 73 20 41 6e 64 20 53 68  al Tables And Sh
5550: 61 72 65 64 20 43 61 63 68 65 3c 2f 68 32 3e 0a  ared Cache</h2>.
5560: 0a 3c 70 3e 50 72 69 6f 72 20 74 6f 20 53 51 4c  .<p>Prior to SQL
5570: 69 74 65 20 3c 61 20 68 72 65 66 3d 22 72 65 6c  ite <a href="rel
5580: 65 61 73 65 6c 6f 67 2f 33 5f 36 5f 31 37 2e 68  easelog/3_6_17.h
5590: 74 6d 6c 22 3e 76 65 72 73 69 6f 6e 20 33 2e 36  tml">version 3.6
55a0: 2e 31 37 3c 2f 61 3e 20 28 32 30 30 39 2d 30 38  .17</a> (2009-08
55b0: 2d 31 30 29 2c 20 0a 74 68 65 20 76 69 72 74 75  -10), .the virtu
55c0: 61 6c 20 74 61 62 6c 65 20 6d 65 63 68 61 6e 69  al table mechani
55d0: 73 6d 20 61 73 73 75 6d 65 73 20 0a 74 68 61 74  sm assumes .that
55e0: 20 65 61 63 68 20 3c 61 20 68 72 65 66 3d 22 63   each <a href="c
55f0: 33 72 65 66 2f 73 71 6c 69 74 65 33 2e 68 74 6d  3ref/sqlite3.htm
5600: 6c 22 3e 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  l">database conn
5610: 65 63 74 69 6f 6e 3c 2f 61 3e 20 6b 65 70 74 0a  ection</a> kept.
5620: 69 74 73 20 6f 77 6e 20 63 6f 70 79 20 6f 66 20  its own copy of 
5630: 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
5640: 65 6d 61 2e 20 48 65 6e 63 65 2c 20 74 68 65 20  ema. Hence, the 
5650: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65  virtual table me
5660: 63 68 61 6e 69 73 6d 0a 63 6f 75 6c 64 20 6e 6f  chanism.could no
5670: 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 64  t be used in a d
5680: 61 74 61 62 61 73 65 20 74 68 61 74 20 68 61 73  atabase that has
5690: 20 3c 61 20 68 72 65 66 3d 22 73 68 61 72 65 64   <a href="shared
56a0: 63 61 63 68 65 2e 68 74 6d 6c 22 3e 73 68 61 72  cache.html">shar
56b0: 65 64 20 63 61 63 68 65 20 6d 6f 64 65 3c 2f 61  ed cache mode</a
56c0: 3e 20 65 6e 61 62 6c 65 64 2e 20 0a 54 68 65 20  > enabled. .The 
56d0: 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f 63  <a href="c3ref/c
56e0: 72 65 61 74 65 5f 6d 6f 64 75 6c 65 2e 68 74 6d  reate_module.htm
56f0: 6c 22 3e 73 71 6c 69 74 65 33 5f 63 72 65 61 74  l">sqlite3_creat
5700: 65 5f 6d 6f 64 75 6c 65 28 29 3c 2f 61 3e 20 69  e_module()</a> i
5710: 6e 74 65 72 66 61 63 65 20 77 6f 75 6c 64 20 72  nterface would r
5720: 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 20 69  eturn an error i
5730: 66 20 0a 3c 61 20 68 72 65 66 3d 22 73 68 61 72  f .<a href="shar
5740: 65 64 63 61 63 68 65 2e 68 74 6d 6c 22 3e 73 68  edcache.html">sh
5750: 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 3c  ared cache mode<
5760: 2f 61 3e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20  /a> is enabled. 
5770: 20 54 68 61 74 20 72 65 73 74 72 69 63 74 69 6f   That restrictio
5780: 6e 20 77 61 73 20 72 65 6c 61 78 65 64 0a 62 65  n was relaxed.be
5790: 67 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c  ginning with SQL
57a0: 69 74 65 20 3c 61 20 68 72 65 66 3d 22 72 65 6c  ite <a href="rel
57b0: 65 61 73 65 6c 6f 67 2f 33 5f 36 5f 31 37 2e 68  easelog/3_6_17.h
57c0: 74 6d 6c 22 3e 76 65 72 73 69 6f 6e 20 33 2e 36  tml">version 3.6
57d0: 2e 31 37 3c 2f 61 3e 2e 0a 0a 3c 2f 70 3e 3c 68  .17</a>...</p><h
57e0: 32 20 69 64 3d 22 63 72 65 61 74 69 6e 67 5f 6e  2 id="creating_n
57f0: 65 77 5f 76 69 72 74 75 61 6c 5f 74 61 62 6c 65  ew_virtual_table
5800: 5f 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73  _implementations
5810: 22 3e 3c 73 70 61 6e 3e 31 2e 34 2e 20 3c 2f 73  "><span>1.4. </s
5820: 70 61 6e 3e 43 72 65 61 74 69 6e 67 20 4e 65 77  pan>Creating New
5830: 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49   Virtual Table I
5840: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 3c 2f  mplementations</
5850: 68 32 3e 0a 0a 3c 70 3e 46 6f 6c 6c 6f 77 20 74  h2>..<p>Follow t
5860: 68 65 73 65 20 73 74 65 70 73 20 74 6f 20 63 72  hese steps to cr
5870: 65 61 74 65 20 79 6f 75 72 20 6f 77 6e 20 76 69  eate your own vi
5880: 72 74 75 61 6c 20 74 61 62 6c 65 3a 0a 0a 3c 2f  rtual table:..</
5890: 70 3e 3c 70 3e 0a 3c 2f 70 3e 3c 6f 6c 3e 0a 3c  p><p>.</p><ol>.<
58a0: 6c 69 3e 20 57 72 69 74 65 20 61 6c 6c 20 6e 65  li> Write all ne
58b0: 63 65 73 73 61 72 79 20 6d 65 74 68 6f 64 73 2e  cessary methods.
58c0: 0a 3c 2f 6c 69 3e 3c 6c 69 3e 20 43 72 65 61 74  .</li><li> Creat
58d0: 65 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  e an instance of
58e0: 20 74 68 65 20 3c 61 20 68 72 65 66 3d 22 63 33   the <a href="c3
58f0: 72 65 66 2f 6d 6f 64 75 6c 65 2e 68 74 6d 6c 22  ref/module.html"
5900: 3e 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3c  >sqlite3_module<
5910: 2f 61 3e 20 73 74 72 75 63 74 75 72 65 20 63 6f  /a> structure co
5920: 6e 74 61 69 6e 69 6e 67 20 70 6f 69 6e 74 65 72  ntaining pointer
5930: 73 0a 20 20 20 20 20 74 6f 20 61 6c 6c 20 74 68  s.     to all th
5940: 65 20 6d 65 74 68 6f 64 73 20 66 72 6f 6d 20 73  e methods from s
5950: 74 65 70 20 31 2e 0a 3c 2f 6c 69 3e 3c 6c 69 3e  tep 1..</li><li>
5960: 20 52 65 67 69 73 74 65 72 20 79 6f 75 72 20 3c   Register your <
5970: 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f 6d 6f  a href="c3ref/mo
5980: 64 75 6c 65 2e 68 74 6d 6c 22 3e 73 71 6c 69 74  dule.html">sqlit
5990: 65 33 5f 6d 6f 64 75 6c 65 3c 2f 61 3e 20 73 74  e3_module</a> st
59a0: 72 75 63 74 75 72 65 20 75 73 69 6e 67 20 6f 6e  ructure using on
59b0: 65 20 6f 66 20 74 68 65 0a 20 20 20 20 20 3c 61  e of the.     <a
59c0: 20 68 72 65 66 3d 22 63 33 72 65 66 2f 63 72 65   href="c3ref/cre
59d0: 61 74 65 5f 6d 6f 64 75 6c 65 2e 68 74 6d 6c 22  ate_module.html"
59e0: 3e 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  >sqlite3_create_
59f0: 6d 6f 64 75 6c 65 28 29 3c 2f 61 3e 20 6f 72 20  module()</a> or 
5a00: 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f 63  <a href="c3ref/c
5a10: 72 65 61 74 65 5f 6d 6f 64 75 6c 65 2e 68 74 6d  reate_module.htm
5a20: 6c 22 3e 73 71 6c 69 74 65 33 5f 63 72 65 61 74  l">sqlite3_creat
5a30: 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 3c 2f 61  e_module_v2()</a
5a40: 3e 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 3c 2f  > interfaces..</
5a50: 6c 69 3e 3c 6c 69 3e 20 52 75 6e 20 61 20 3c 61  li><li> Run a <a
5a60: 20 68 72 65 66 3d 22 6c 61 6e 67 5f 63 72 65 61   href="lang_crea
5a70: 74 65 76 74 61 62 2e 68 74 6d 6c 22 3e 43 52 45  tevtab.html">CRE
5a80: 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c  ATE VIRTUAL TABL
5a90: 45 3c 2f 61 3e 20 63 6f 6d 6d 61 6e 64 20 74 68  E</a> command th
5aa0: 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  at specifies the
5ab0: 20 6e 65 77 20 6d 6f 64 75 6c 65 20 69 6e 20 0a   new module in .
5ac0: 20 20 20 20 20 74 68 65 20 55 53 49 4e 47 20 63       the USING c
5ad0: 6c 61 75 73 65 2e 20 0a 3c 2f 6c 69 3e 3c 2f 6f  lause. .</li></o
5ae0: 6c 3e 0a 0a 3c 70 3e 54 68 65 20 6f 6e 6c 79 20  l>..<p>The only 
5af0: 72 65 61 6c 6c 79 20 68 61 72 64 20 70 61 72 74  really hard part
5b00: 20 69 73 20 73 74 65 70 20 31 2e 20 59 6f 75 20   is step 1. You 
5b10: 6d 69 67 68 74 20 77 61 6e 74 20 74 6f 20 73 74  might want to st
5b20: 61 72 74 20 77 69 74 68 20 61 6e 20 0a 65 78 69  art with an .exi
5b30: 73 74 69 6e 67 20 76 69 72 74 75 61 6c 20 74 61  sting virtual ta
5b40: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
5b50: 6f 6e 20 61 6e 64 20 6d 6f 64 69 66 79 20 69 74  on and modify it
5b60: 20 74 6f 20 73 75 69 74 20 79 6f 75 72 20 6e 65   to suit your ne
5b70: 65 64 73 2e 0a 54 68 65 72 65 20 61 72 65 20 73  eds..There are s
5b80: 65 76 65 72 61 6c 20 76 69 72 74 75 61 6c 20 74  everal virtual t
5b90: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
5ba0: 69 6f 6e 73 20 69 6e 20 74 68 65 20 53 51 4c 69  ions in the SQLi
5bb0: 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 20 0a  te source tree .
5bc0: 28 66 6f 72 20 74 65 73 74 69 6e 67 20 70 75 72  (for testing pur
5bd0: 70 6f 73 65 73 29 2e 20 59 6f 75 20 6d 69 67 68  poses). You migh
5be0: 74 20 75 73 65 20 6f 6e 65 20 6f 66 20 74 68 6f  t use one of tho
5bf0: 73 65 20 61 73 20 61 20 67 75 69 64 65 2e 20 4c  se as a guide. L
5c00: 6f 63 61 74 65 20 0a 74 68 65 73 65 20 74 65 73  ocate .these tes
5c10: 74 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  t virtual table 
5c20: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
5c30: 62 79 20 73 65 61 72 63 68 69 6e 67 20 0a 66 6f  by searching .fo
5c40: 72 20 22 73 71 6c 69 74 65 33 5f 63 72 65 61 74  r "sqlite3_creat
5c50: 65 5f 6d 6f 64 75 6c 65 22 2e 0a 0a 3c 2f 70 3e  e_module"...</p>
5c60: 3c 70 3e 59 6f 75 20 6d 69 67 68 74 20 61 6c 73  <p>You might als
5c70: 6f 20 77 61 6e 74 20 74 6f 20 69 6d 70 6c 65 6d  o want to implem
5c80: 65 6e 74 20 79 6f 75 72 20 6e 65 77 20 76 69 72  ent your new vir
5c90: 74 75 61 6c 20 74 61 62 6c 65 20 61 73 20 61 20  tual table as a 
5ca0: 0a 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f  .<a href="c3ref/
5cb0: 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 2e 68  load_extension.h
5cc0: 74 6d 6c 22 3e 6c 6f 61 64 61 62 6c 65 20 65 78  tml">loadable ex
5cd0: 74 65 6e 73 69 6f 6e 3c 2f 61 3e 2e 0a 0a 3c 2f  tension</a>...</
5ce0: 70 3e 3c 68 31 20 69 64 3d 22 76 69 72 74 75 61  p><h1 id="virtua
5cf0: 6c 5f 74 61 62 6c 65 5f 6d 65 74 68 6f 64 73 22  l_table_methods"
5d00: 3e 3c 73 70 61 6e 3e 32 2e 20 3c 2f 73 70 61 6e  ><span>2. </span
5d10: 3e 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4d  >Virtual Table M
5d20: 65 74 68 6f 64 73 3c 2f 68 31 3e 0a 0a 3c 61 20  ethods</h1>..<a 
5d30: 6e 61 6d 65 3d 22 78 63 72 65 61 74 65 22 3e 3c  name="xcreate"><
5d40: 2f 61 3e 0a 0a 3c 68 32 20 69 64 3d 22 74 68 65  /a>..<h2 id="the
5d50: 5f 78 63 72 65 61 74 65 5f 6d 65 74 68 6f 64 22  _xcreate_method"
5d60: 3e 3c 73 70 61 6e 3e 32 2e 31 2e 20 3c 2f 73 70  ><span>2.1. </sp
5d70: 61 6e 3e 54 68 65 20 78 43 72 65 61 74 65 20 4d  an>The xCreate M
5d80: 65 74 68 6f 64 3c 2f 68 32 3e 0a 0a 3c 64 69 76  ethod</h2>..<div
5d90: 20 63 6c 61 73 73 3d 22 63 6f 64 65 62 6c 6f 63   class="codebloc
5da0: 6b 22 3e 3c 70 72 65 3e 69 6e 74 20 28 2a 78 43  k"><pre>int (*xC
5db0: 72 65 61 74 65 29 28 73 71 6c 69 74 65 33 20 2a  reate)(sqlite3 *
5dc0: 64 62 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a  db, void *pAux,.
5dd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
5de0: 20 61 72 67 63 2c 20 63 68 61 72 20 2a 2a 61 72   argc, char **ar
5df0: 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  gv,.            
5e00: 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a   sqlite3_vtab **
5e10: 70 70 56 54 61 62 2c 0a 20 20 20 20 20 20 20 20  ppVTab,.        
5e20: 20 20 20 20 20 63 68 61 72 20 2a 2a 70 7a 45 72       char **pzEr
5e30: 72 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 64 69 76 3e  r);.</pre></div>
5e40: 0a 0a 3c 70 3e 54 68 65 20 78 43 72 65 61 74 65  ..<p>The xCreate
5e50: 20 6d 65 74 68 6f 64 20 69 73 20 63 61 6c 6c 65   method is calle
5e60: 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 6e 65  d to create a ne
5e70: 77 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 61 20  w instance of a 
5e80: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 0a 69  virtual table .i
5e90: 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
5ea0: 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 63 72  <a href="lang_cr
5eb0: 65 61 74 65 76 74 61 62 2e 68 74 6d 6c 22 3e 43  eatevtab.html">C
5ec0: 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41  REATE VIRTUAL TA
5ed0: 42 4c 45 3c 2f 61 3e 20 73 74 61 74 65 6d 65 6e  BLE</a> statemen
5ee0: 74 2e 0a 49 66 20 74 68 65 20 78 43 72 65 61 74  t..If the xCreat
5ef0: 65 20 6d 65 74 68 6f 64 20 69 73 20 74 68 65 20  e method is the 
5f00: 73 61 6d 65 20 70 6f 69 6e 74 65 72 20 61 73 20  same pointer as 
5f10: 74 68 65 20 3c 61 20 68 72 65 66 3d 22 76 74 61  the <a href="vta
5f20: 62 2e 68 74 6d 6c 23 78 63 6f 6e 6e 65 63 74 22  b.html#xconnect"
5f30: 3e 78 43 6f 6e 6e 65 63 74 3c 2f 61 3e 20 6d 65  >xConnect</a> me
5f40: 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 0a 76  thod, then the.v
5f50: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20  irtual table is 
5f60: 61 6e 20 3c 61 20 68 72 65 66 3d 22 76 74 61 62  an <a href="vtab
5f70: 2e 68 74 6d 6c 23 65 70 6f 76 74 61 62 22 3e 65  .html#epovtab">e
5f80: 70 6f 6e 79 6d 6f 75 73 20 76 69 72 74 75 61 6c  ponymous virtual
5f90: 20 74 61 62 6c 65 3c 2f 61 3e 2e 0a 49 66 20 74   table</a>..If t
5fa0: 68 65 20 78 43 72 65 61 74 65 20 6d 65 74 68 6f  he xCreate metho
5fb0: 64 20 69 73 20 6f 6d 69 74 74 65 64 20 28 69 66  d is omitted (if
5fc0: 20 69 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f   it is a NULL po
5fd0: 69 6e 74 65 72 29 20 74 68 65 6e 20 74 68 65 20  inter) then the 
5fe0: 76 69 72 74 75 61 6c 20 0a 74 61 62 6c 65 20 69  virtual .table i
5ff0: 73 20 61 6e 20 3c 61 20 68 72 65 66 3d 22 76 74  s an <a href="vt
6000: 61 62 2e 68 74 6d 6c 23 65 70 6f 6f 6e 6c 79 76  ab.html#epoonlyv
6010: 74 61 62 22 3e 65 70 6f 6e 79 6d 6f 75 73 2d 6f  tab">eponymous-o
6020: 6e 6c 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c  nly virtual tabl
6030: 65 3c 2f 61 3e 2e 0a 0a 0a 3c 2f 70 3e 3c 70 3e  e</a>....</p><p>
6040: 54 68 65 20 64 62 20 70 61 72 61 6d 65 74 65 72  The db parameter
6050: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
6060: 20 74 68 65 20 53 51 4c 69 74 65 20 3c 61 20 68   the SQLite <a h
6070: 72 65 66 3d 22 63 33 72 65 66 2f 73 71 6c 69 74  ref="c3ref/sqlit
6080: 65 33 2e 68 74 6d 6c 22 3e 64 61 74 61 62 61 73  e3.html">databas
6090: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 3c 2f 61 3e  e connection</a>
60a0: 20 74 68 61 74 20 0a 69 73 20 65 78 65 63 75 74   that .is execut
60b0: 69 6e 67 20 74 68 65 20 3c 61 20 68 72 65 66 3d  ing the <a href=
60c0: 22 6c 61 6e 67 5f 63 72 65 61 74 65 76 74 61 62  "lang_createvtab
60d0: 2e 68 74 6d 6c 22 3e 43 52 45 41 54 45 20 56 49  .html">CREATE VI
60e0: 52 54 55 41 4c 20 54 41 42 4c 45 3c 2f 61 3e 20  RTUAL TABLE</a> 
60f0: 73 74 61 74 65 6d 65 6e 74 2e 20 0a 54 68 65 20  statement. .The 
6100: 70 41 75 78 20 61 72 67 75 6d 65 6e 74 20 69 73  pAux argument is
6110: 20 74 68 65 20 63 6f 70 79 20 6f 66 20 74 68 65   the copy of the
6120: 20 63 6c 69 65 6e 74 20 64 61 74 61 20 70 6f 69   client data poi
6130: 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68  nter that was th
6140: 65 20 0a 66 6f 75 72 74 68 20 61 72 67 75 6d 65  e .fourth argume
6150: 6e 74 20 74 6f 20 74 68 65 20 3c 61 20 68 72 65  nt to the <a hre
6160: 66 3d 22 63 33 72 65 66 2f 63 72 65 61 74 65 5f  f="c3ref/create_
6170: 6d 6f 64 75 6c 65 2e 68 74 6d 6c 22 3e 73 71 6c  module.html">sql
6180: 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
6190: 6c 65 28 29 3c 2f 61 3e 20 6f 72 0a 3c 61 20 68  le()</a> or.<a h
61a0: 72 65 66 3d 22 63 33 72 65 66 2f 63 72 65 61 74  ref="c3ref/creat
61b0: 65 5f 6d 6f 64 75 6c 65 2e 68 74 6d 6c 22 3e 73  e_module.html">s
61c0: 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
61d0: 64 75 6c 65 5f 76 32 28 29 3c 2f 61 3e 20 63 61  dule_v2()</a> ca
61e0: 6c 6c 20 74 68 61 74 20 72 65 67 69 73 74 65 72  ll that register
61f0: 65 64 20 74 68 65 20 0a 3c 61 20 68 72 65 66 3d  ed the .<a href=
6200: 22 63 33 72 65 66 2f 6d 6f 64 75 6c 65 2e 68 74  "c3ref/module.ht
6210: 6d 6c 22 3e 76 69 72 74 75 61 6c 20 74 61 62 6c  ml">virtual tabl
6220: 65 20 6d 6f 64 75 6c 65 3c 2f 61 3e 2e 20 0a 54  e module</a>. .T
6230: 68 65 20 61 72 67 76 20 70 61 72 61 6d 65 74 65  he argv paramete
6240: 72 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  r is an array of
6250: 20 61 72 67 63 20 70 6f 69 6e 74 65 72 73 20 74   argc pointers t
6260: 6f 20 6e 75 6c 6c 20 74 65 72 6d 69 6e 61 74 65  o null terminate
6270: 64 20 73 74 72 69 6e 67 73 2e 20 0a 54 68 65 20  d strings. .The 
6280: 66 69 72 73 74 20 73 74 72 69 6e 67 2c 20 61 72  first string, ar
6290: 67 76 5b 30 5d 2c 20 69 73 20 74 68 65 20 6e 61  gv[0], is the na
62a0: 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  me of the module
62b0: 20 62 65 69 6e 67 20 69 6e 76 6f 6b 65 64 2e 20   being invoked. 
62c0: 20 20 54 68 65 0a 6d 6f 64 75 6c 65 20 6e 61 6d    The.module nam
62d0: 65 20 69 73 20 74 68 65 20 6e 61 6d 65 20 70 72  e is the name pr
62e0: 6f 76 69 64 65 64 20 61 73 20 74 68 65 20 73 65  ovided as the se
62f0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
6300: 20 0a 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66   .<a href="c3ref
6310: 2f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 2e 68  /create_module.h
6320: 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 63 72 65  tml">sqlite3_cre
6330: 61 74 65 5f 6d 6f 64 75 6c 65 28 29 3c 2f 61 3e  ate_module()</a>
6340: 20 61 6e 64 20 61 73 20 74 68 65 20 61 72 67 75   and as the argu
6350: 6d 65 6e 74 20 74 6f 20 74 68 65 20 55 53 49 4e  ment to the USIN
6360: 47 20 63 6c 61 75 73 65 20 6f 66 20 74 68 65 0a  G clause of the.
6370: 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 63 72  <a href="lang_cr
6380: 65 61 74 65 76 74 61 62 2e 68 74 6d 6c 22 3e 43  eatevtab.html">C
6390: 52 45 41 54 45 20 56 49 52 54 55 41 4c 20 54 41  REATE VIRTUAL TA
63a0: 42 4c 45 3c 2f 61 3e 20 73 74 61 74 65 6d 65 6e  BLE</a> statemen
63b0: 74 20 74 68 61 74 20 69 73 20 72 75 6e 6e 69 6e  t that is runnin
63c0: 67 2e 0a 54 68 65 20 73 65 63 6f 6e 64 2c 20 61  g..The second, a
63d0: 72 67 76 5b 31 5d 2c 20 69 73 20 74 68 65 20 6e  rgv[1], is the n
63e0: 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
63f0: 61 73 65 20 69 6e 20 77 68 69 63 68 20 74 68 65  ase in which the
6400: 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61 62   new virtual tab
6410: 6c 65 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  le is being crea
6420: 74 65 64 2e 20 54 68 65 20 64 61 74 61 62 61 73  ted. The databas
6430: 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e 22  e name is "main"
6440: 20 66 6f 72 20 74 68 65 20 70 72 69 6d 61 72 79   for the primary
6450: 20 64 61 74 61 62 61 73 65 2c 20 6f 72 0a 22 74   database, or."t
6460: 65 6d 70 22 20 66 6f 72 20 54 45 4d 50 20 64 61  emp" for TEMP da
6470: 74 61 62 61 73 65 2c 20 6f 72 20 74 68 65 20 6e  tabase, or the n
6480: 61 6d 65 20 67 69 76 65 6e 20 61 74 20 74 68 65  ame given at the
6490: 20 65 6e 64 20 6f 66 20 74 68 65 20 3c 61 20 68   end of the <a h
64a0: 72 65 66 3d 22 6c 61 6e 67 5f 61 74 74 61 63 68  ref="lang_attach
64b0: 2e 68 74 6d 6c 22 3e 41 54 54 41 43 48 3c 2f 61  .html">ATTACH</a
64c0: 3e 0a 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  >.statement for 
64d0: 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
64e0: 65 73 2e 20 20 54 68 65 20 74 68 69 72 64 20 65  es.  The third e
64f0: 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72  lement of the ar
6500: 72 61 79 2c 20 61 72 67 76 5b 32 5d 2c 20 0a 69  ray, argv[2], .i
6510: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
6520: 65 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61  e new virtual ta
6530: 62 6c 65 2c 20 61 73 20 73 70 65 63 69 66 69 65  ble, as specifie
6540: 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 65 20  d following the 
6550: 54 41 42 4c 45 0a 6b 65 79 77 6f 72 64 20 69 6e  TABLE.keyword in
6560: 20 74 68 65 20 3c 61 20 68 72 65 66 3d 22 6c 61   the <a href="la
6570: 6e 67 5f 63 72 65 61 74 65 76 74 61 62 2e 68 74  ng_createvtab.ht
6580: 6d 6c 22 3e 43 52 45 41 54 45 20 56 49 52 54 55  ml">CREATE VIRTU
6590: 41 4c 20 54 41 42 4c 45 3c 2f 61 3e 20 73 74 61  AL TABLE</a> sta
65a0: 74 65 6d 65 6e 74 2e 0a 49 66 20 70 72 65 73 65  tement..If prese
65b0: 6e 74 2c 20 74 68 65 20 66 6f 75 72 74 68 20 61  nt, the fourth a
65c0: 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 73 74  nd subsequent st
65d0: 72 69 6e 67 73 20 69 6e 20 74 68 65 20 61 72 67  rings in the arg
65e0: 76 5b 5d 20 61 72 72 61 79 20 72 65 70 6f 72 74  v[] array report
65f0: 20 0a 74 68 65 20 61 72 67 75 6d 65 6e 74 73 20   .the arguments 
6600: 74 6f 20 74 68 65 20 6d 6f 64 75 6c 65 20 6e 61  to the module na
6610: 6d 65 20 69 6e 20 74 68 65 20 3c 61 20 68 72 65  me in the <a hre
6620: 66 3d 22 6c 61 6e 67 5f 63 72 65 61 74 65 76 74  f="lang_createvt
6630: 61 62 2e 68 74 6d 6c 22 3e 43 52 45 41 54 45 20  ab.html">CREATE 
6640: 56 49 52 54 55 41 4c 20 54 41 42 4c 45 3c 2f 61  VIRTUAL TABLE</a
6650: 3e 20 73 74 61 74 65 6d 65 6e 74 2e 0a 0a 3c 2f  > statement...</
6660: 70 3e 3c 70 3e 54 68 65 20 6a 6f 62 20 6f 66 20  p><p>The job of 
6670: 74 68 69 73 20 6d 65 74 68 6f 64 20 69 73 20 74  this method is t
6680: 6f 20 63 6f 6e 73 74 72 75 63 74 20 74 68 65 20  o construct the 
6690: 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c  new virtual tabl
66a0: 65 20 6f 62 6a 65 63 74 0a 28 61 6e 20 3c 61 20  e object.(an <a 
66b0: 68 72 65 66 3d 22 63 33 72 65 66 2f 76 74 61 62  href="c3ref/vtab
66c0: 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 76  .html">sqlite3_v
66d0: 74 61 62 3c 2f 61 3e 20 6f 62 6a 65 63 74 29 20  tab</a> object) 
66e0: 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69  and return a poi
66f0: 6e 74 65 72 20 74 6f 20 69 74 20 69 6e 20 2a 70  nter to it in *p
6700: 70 56 54 61 62 2e 0a 0a 3c 2f 70 3e 3c 70 3e 41  pVTab...</p><p>A
6710: 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 61  s part of the ta
6720: 73 6b 20 6f 66 20 63 72 65 61 74 69 6e 67 20 61  sk of creating a
6730: 20 6e 65 77 20 3c 61 20 68 72 65 66 3d 22 63 33   new <a href="c3
6740: 72 65 66 2f 76 74 61 62 2e 68 74 6d 6c 22 3e 73  ref/vtab.html">s
6750: 71 6c 69 74 65 33 5f 76 74 61 62 3c 2f 61 3e 20  qlite3_vtab</a> 
6760: 73 74 72 75 63 74 75 72 65 2c 20 74 68 69 73 20  structure, this 
6770: 0a 6d 65 74 68 6f 64 20 3c 75 3e 6d 75 73 74 3c  .method <u>must<
6780: 2f 75 3e 20 69 6e 76 6f 6b 65 20 3c 61 20 68 72  /u> invoke <a hr
6790: 65 66 3d 22 63 33 72 65 66 2f 64 65 63 6c 61 72  ef="c3ref/declar
67a0: 65 5f 76 74 61 62 2e 68 74 6d 6c 22 3e 73 71 6c  e_vtab.html">sql
67b0: 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61  ite3_declare_vta
67c0: 62 28 29 3c 2f 61 3e 20 74 6f 20 74 65 6c 6c 20  b()</a> to tell 
67d0: 74 68 65 20 53 51 4c 69 74 65 20 0a 63 6f 72 65  the SQLite .core
67e0: 20 61 62 6f 75 74 20 74 68 65 20 63 6f 6c 75 6d   about the colum
67f0: 6e 73 20 61 6e 64 20 64 61 74 61 74 79 70 65 73  ns and datatypes
6800: 20 69 6e 20 74 68 65 20 76 69 72 74 75 61 6c 20   in the virtual 
6810: 74 61 62 6c 65 2e 20 0a 54 68 65 20 3c 61 20 68  table. .The <a h
6820: 72 65 66 3d 22 63 33 72 65 66 2f 64 65 63 6c 61  ref="c3ref/decla
6830: 72 65 5f 76 74 61 62 2e 68 74 6d 6c 22 3e 73 71  re_vtab.html">sq
6840: 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74  lite3_declare_vt
6850: 61 62 28 29 3c 2f 61 3e 20 41 50 49 20 68 61 73  ab()</a> API has
6860: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70   the following p
6870: 72 6f 74 6f 74 79 70 65 3a 0a 0a 3c 2f 70 3e 3c  rototype:..</p><
6880: 64 69 76 20 63 6c 61 73 73 3d 22 63 6f 64 65 62  div class="codeb
6890: 6c 6f 63 6b 22 3e 3c 70 72 65 3e 69 6e 74 20 73  lock"><pre>int s
68a0: 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76  qlite3_declare_v
68b0: 74 61 62 28 73 71 6c 69 74 65 33 20 2a 64 62 2c  tab(sqlite3 *db,
68c0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 72   const char *zCr
68d0: 65 61 74 65 54 61 62 6c 65 29 0a 3c 2f 70 72 65  eateTable).</pre
68e0: 3e 3c 2f 64 69 76 3e 0a 0a 3c 70 3e 54 68 65 20  ></div>..<p>The 
68f0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
6900: 6f 20 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66  o <a href="c3ref
6910: 2f 64 65 63 6c 61 72 65 5f 76 74 61 62 2e 68 74  /declare_vtab.ht
6920: 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 64 65 63 6c  ml">sqlite3_decl
6930: 61 72 65 5f 76 74 61 62 28 29 3c 2f 61 3e 20 6d  are_vtab()</a> m
6940: 75 73 74 20 62 65 20 74 68 65 20 73 61 6d 65 20  ust be the same 
6950: 0a 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f  .<a href="c3ref/
6960: 73 71 6c 69 74 65 33 2e 68 74 6d 6c 22 3e 64 61  sqlite3.html">da
6970: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
6980: 6e 3c 2f 61 3e 20 70 6f 69 6e 74 65 72 20 61 73  n</a> pointer as
6990: 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
69a0: 65 74 65 72 20 74 6f 20 74 68 69 73 20 6d 65 74  eter to this met
69b0: 68 6f 64 2e 0a 54 68 65 20 73 65 63 6f 6e 64 20  hod..The second 
69c0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 3c 61 20 68  argument to <a h
69d0: 72 65 66 3d 22 63 33 72 65 66 2f 64 65 63 6c 61  ref="c3ref/decla
69e0: 72 65 5f 76 74 61 62 2e 68 74 6d 6c 22 3e 73 71  re_vtab.html">sq
69f0: 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74  lite3_declare_vt
6a00: 61 62 28 29 3c 2f 61 3e 20 6d 75 73 74 20 61 20  ab()</a> must a 
6a10: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
6a20: 0a 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68  .UTF-8 string th
6a30: 61 74 20 63 6f 6e 74 61 69 6e 73 20 61 20 77 65  at contains a we
6a40: 6c 6c 2d 66 6f 72 6d 65 64 20 3c 61 20 68 72 65  ll-formed <a hre
6a50: 66 3d 22 6c 61 6e 67 5f 63 72 65 61 74 65 74 61  f="lang_createta
6a60: 62 6c 65 2e 68 74 6d 6c 22 3e 43 52 45 41 54 45  ble.html">CREATE
6a70: 20 54 41 42 4c 45 3c 2f 61 3e 20 73 74 61 74 65   TABLE</a> state
6a80: 6d 65 6e 74 20 74 68 61 74 20 0a 64 65 66 69 6e  ment that .defin
6a90: 65 73 20 74 68 65 20 63 6f 6c 75 6d 6e 73 20 69  es the columns i
6aa0: 6e 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  n the virtual ta
6ab0: 62 6c 65 20 61 6e 64 20 74 68 65 69 72 20 64 61  ble and their da
6ac0: 74 61 20 74 79 70 65 73 2e 20 0a 54 68 65 20 6e  ta types. .The n
6ad0: 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ame of the table
6ae0: 20 69 6e 20 74 68 69 73 20 43 52 45 41 54 45 20   in this CREATE 
6af0: 54 41 42 4c 45 20 73 74 61 74 65 6d 65 6e 74 20  TABLE statement 
6b00: 69 73 20 69 67 6e 6f 72 65 64 2c 20 0a 61 73 20  is ignored, .as 
6b10: 61 72 65 20 61 6c 6c 20 63 6f 6e 73 74 72 61 69  are all constrai
6b20: 6e 74 73 2e 20 4f 6e 6c 79 20 74 68 65 20 63 6f  nts. Only the co
6b30: 6c 75 6d 6e 20 6e 61 6d 65 73 20 61 6e 64 20 64  lumn names and d
6b40: 61 74 61 74 79 70 65 73 20 6d 61 74 74 65 72 2e  atatypes matter.
6b50: 0a 54 68 65 20 43 52 45 41 54 45 20 54 41 42 4c  .The CREATE TABL
6b60: 45 20 73 74 61 74 65 6d 65 6e 74 20 73 74 72 69  E statement stri
6b70: 6e 67 20 6e 65 65 64 20 6e 6f 74 20 74 6f 20 62  ng need not to b
6b80: 65 20 0a 68 65 6c 64 20 69 6e 20 70 65 72 73 69  e .held in persi
6b90: 73 74 65 6e 74 20 6d 65 6d 6f 72 79 2e 20 20 54  stent memory.  T
6ba0: 68 65 20 73 74 72 69 6e 67 20 63 61 6e 20 62 65  he string can be
6bb0: 0a 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 6e 64  .deallocated and
6bc0: 2f 6f 72 20 72 65 75 73 65 64 20 61 73 20 73 6f  /or reused as so
6bd0: 6f 6e 20 61 73 20 74 68 65 20 3c 61 20 68 72 65  on as the <a hre
6be0: 66 3d 22 63 33 72 65 66 2f 64 65 63 6c 61 72 65  f="c3ref/declare
6bf0: 5f 76 74 61 62 2e 68 74 6d 6c 22 3e 73 71 6c 69  _vtab.html">sqli
6c00: 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62  te3_declare_vtab
6c10: 28 29 3c 2f 61 3e 0a 72 6f 75 74 69 6e 65 20 72  ()</a>.routine r
6c20: 65 74 75 72 6e 73 2e 0a 0a 3c 2f 70 3e 3c 70 3e  eturns...</p><p>
6c30: 54 68 65 20 78 43 72 65 61 74 65 20 6d 65 74 68  The xCreate meth
6c40: 6f 64 20 6e 65 65 64 20 6e 6f 74 20 69 6e 69 74  od need not init
6c50: 69 61 6c 69 7a 65 20 74 68 65 20 70 4d 6f 64 75  ialize the pModu
6c60: 6c 65 2c 20 6e 52 65 66 2c 20 61 6e 64 20 7a 45  le, nRef, and zE
6c70: 72 72 4d 73 67 0a 66 69 65 6c 64 73 20 6f 66 20  rrMsg.fields of 
6c80: 74 68 65 20 3c 61 20 68 72 65 66 3d 22 63 33 72  the <a href="c3r
6c90: 65 66 2f 76 74 61 62 2e 68 74 6d 6c 22 3e 73 71  ef/vtab.html">sq
6ca0: 6c 69 74 65 33 5f 76 74 61 62 3c 2f 61 3e 20 6f  lite3_vtab</a> o
6cb0: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69  bject.  The SQLi
6cc0: 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 74 61 6b  te core will tak
6cd0: 65 20 63 61 72 65 20 6f 66 20 0a 74 68 61 74 20  e care of .that 
6ce0: 63 68 6f 72 65 2e 0a 0a 3c 2f 70 3e 3c 70 3e 54  chore...</p><p>T
6cf0: 68 65 20 78 43 72 65 61 74 65 20 73 68 6f 75 6c  he xCreate shoul
6d00: 64 20 72 65 74 75 72 6e 20 3c 61 20 68 72 65 66  d return <a href
6d10: 3d 22 72 65 73 63 6f 64 65 2e 68 74 6d 6c 23 6f  ="rescode.html#o
6d20: 6b 22 3e 53 51 4c 49 54 45 5f 4f 4b 3c 2f 61 3e  k">SQLITE_OK</a>
6d30: 20 69 66 20 69 74 20 69 73 20 73 75 63 63 65 73   if it is succes
6d40: 73 66 75 6c 20 69 6e 20 0a 63 72 65 61 74 69 6e  sful in .creatin
6d50: 67 20 74 68 65 20 6e 65 77 20 76 69 72 74 75 61  g the new virtua
6d60: 6c 20 74 61 62 6c 65 2c 20 6f 72 20 3c 61 20 68  l table, or <a h
6d70: 72 65 66 3d 22 72 65 73 63 6f 64 65 2e 68 74 6d  ref="rescode.htm
6d80: 6c 23 65 72 72 6f 72 22 3e 53 51 4c 49 54 45 5f  l#error">SQLITE_
6d90: 45 52 52 4f 52 3c 2f 61 3e 20 69 66 20 69 74 20  ERROR</a> if it 
6da0: 69 73 20 6e 6f 74 20 73 75 63 63 65 73 73 66 75  is not successfu
6db0: 6c 2e 0a 49 66 20 6e 6f 74 20 73 75 63 63 65 73  l..If not succes
6dc0: 73 66 75 6c 2c 20 74 68 65 20 3c 61 20 68 72 65  sful, the <a hre
6dd0: 66 3d 22 63 33 72 65 66 2f 76 74 61 62 2e 68 74  f="c3ref/vtab.ht
6de0: 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 76 74 61 62  ml">sqlite3_vtab
6df0: 3c 2f 61 3e 20 73 74 72 75 63 74 75 72 65 20 6d  </a> structure m
6e00: 75 73 74 20 6e 6f 74 20 62 65 20 61 6c 6c 6f 63  ust not be alloc
6e10: 61 74 65 64 2e 20 0a 41 6e 20 65 72 72 6f 72 20  ated. .An error 
6e20: 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 70 74 69  message may opti
6e30: 6f 6e 61 6c 6c 79 20 62 65 20 72 65 74 75 72 6e  onally be return
6e40: 65 64 20 69 6e 20 2a 70 7a 45 72 72 20 69 66 20  ed in *pzErr if 
6e50: 75 6e 73 75 63 63 65 73 73 66 75 6c 2e 0a 53 70  unsuccessful..Sp
6e60: 61 63 65 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ace to hold the 
6e70: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
6e80: 72 69 6e 67 20 6d 75 73 74 20 62 65 20 61 6c 6c  ring must be all
6e90: 6f 63 61 74 65 64 20 75 73 69 6e 67 0a 61 6e 20  ocated using.an 
6ea0: 53 51 4c 69 74 65 20 6d 65 6d 6f 72 79 20 61 6c  SQLite memory al
6eb0: 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
6ec0: 6e 20 6c 69 6b 65 20 0a 3c 61 20 68 72 65 66 3d  n like .<a href=
6ed0: 22 63 33 72 65 66 2f 66 72 65 65 2e 68 74 6d 6c  "c3ref/free.html
6ee0: 22 3e 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  ">sqlite3_malloc
6ef0: 28 29 3c 2f 61 3e 20 6f 72 20 3c 61 20 68 72 65  ()</a> or <a hre
6f00: 66 3d 22 63 33 72 65 66 2f 6d 70 72 69 6e 74 66  f="c3ref/mprintf
6f10: 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 6d  .html">sqlite3_m
6f20: 70 72 69 6e 74 66 28 29 3c 2f 61 3e 20 61 73 20  printf()</a> as 
6f30: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
6f40: 77 69 6c 6c 0a 61 74 74 65 6d 70 74 20 74 6f 20  will.attempt to 
6f50: 66 72 65 65 20 74 68 65 20 73 70 61 63 65 20 75  free the space u
6f60: 73 69 6e 67 20 3c 61 20 68 72 65 66 3d 22 63 33  sing <a href="c3
6f70: 72 65 66 2f 66 72 65 65 2e 68 74 6d 6c 22 3e 73  ref/free.html">s
6f80: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 3c 2f 61  qlite3_free()</a
6f90: 3e 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f  > after the erro
6fa0: 72 20 68 61 73 0a 62 65 65 6e 20 72 65 70 6f 72  r has.been repor
6fb0: 74 65 64 20 75 70 20 74 6f 20 74 68 65 20 61 70  ted up to the ap
6fc0: 70 6c 69 63 61 74 69 6f 6e 2e 0a 0a 3c 2f 70 3e  plication...</p>
6fd0: 3c 70 3e 0a 49 66 20 74 68 65 20 78 43 72 65 61  <p>.If the xCrea
6fe0: 74 65 20 6d 65 74 68 6f 64 20 69 73 20 6f 6d 69  te method is omi
6ff0: 74 74 65 64 20 28 6c 65 66 74 20 61 73 20 61 20  tted (left as a 
7000: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 29 20 74 68  NULL pointer) th
7010: 65 6e 20 74 68 65 0a 76 69 72 74 75 61 6c 20 74  en the.virtual t
7020: 61 62 6c 65 20 69 73 20 61 6e 20 3c 61 20 68 72  able is an <a hr
7030: 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23 65 70  ef="vtab.html#ep
7040: 6f 6f 6e 6c 79 76 74 61 62 22 3e 65 70 6f 6e 79  oonlyvtab">epony
7050: 6d 6f 75 73 2d 6f 6e 6c 79 20 76 69 72 74 75 61  mous-only virtua
7060: 6c 20 74 61 62 6c 65 3c 2f 61 3e 2e 20 20 4e 65  l table</a>.  Ne
7070: 77 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 0a 74  w instances of.t
7080: 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
7090: 20 63 61 6e 6e 6f 74 20 62 65 20 63 72 65 61 74   cannot be creat
70a0: 65 64 20 75 73 69 6e 67 20 3c 61 20 68 72 65 66  ed using <a href
70b0: 3d 22 6c 61 6e 67 5f 63 72 65 61 74 65 76 74 61  ="lang_createvta
70c0: 62 2e 68 74 6d 6c 22 3e 43 52 45 41 54 45 20 56  b.html">CREATE V
70d0: 49 52 54 55 41 4c 20 54 41 42 4c 45 3c 2f 61 3e  IRTUAL TABLE</a>
70e0: 20 61 6e 64 20 74 68 65 0a 76 69 72 74 75 61 6c   and the.virtual
70f0: 20 74 61 62 6c 65 20 63 61 6e 20 6f 6e 6c 79 20   table can only 
7100: 62 65 20 75 73 65 64 20 76 69 61 20 69 74 73 20  be used via its 
7110: 6d 6f 64 75 6c 65 20 6e 61 6d 65 2e 0a 4e 6f 74  module name..Not
7120: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 76 65  e that SQLite ve
7130: 72 73 69 6f 6e 73 20 70 72 69 6f 72 20 74 6f 20  rsions prior to 
7140: 33 2e 39 2e 30 20 28 32 30 31 35 2d 31 30 2d 31  3.9.0 (2015-10-1
7150: 34 29 20 64 6f 20 6e 6f 74 20 75 6e 64 65 72 73  4) do not unders
7160: 74 61 6e 64 0a 65 70 6f 6e 79 6d 6f 75 73 2d 6f  tand.eponymous-o
7170: 6e 6c 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c  nly virtual tabl
7180: 65 73 20 61 6e 64 20 77 69 6c 6c 20 73 65 67 66  es and will segf
7190: 61 75 6c 74 20 69 66 20 61 6e 20 61 74 74 65 6d  ault if an attem
71a0: 70 74 20 69 73 20 6d 61 64 65 0a 74 6f 20 3c 61  pt is made.to <a
71b0: 20 68 72 65 66 3d 22 6c 61 6e 67 5f 63 72 65 61   href="lang_crea
71c0: 74 65 76 74 61 62 2e 68 74 6d 6c 22 3e 43 52 45  tevtab.html">CRE
71d0: 41 54 45 20 56 49 52 54 55 41 4c 20 54 41 42 4c  ATE VIRTUAL TABL
71e0: 45 3c 2f 61 3e 20 6f 6e 20 61 6e 20 65 70 6f 6e  E</a> on an epon
71f0: 79 6d 6f 75 73 2d 6f 6e 6c 79 20 76 69 72 74 75  ymous-only virtu
7200: 61 6c 20 74 61 62 6c 65 20 62 65 63 61 75 73 65  al table because
7210: 0a 74 68 65 20 78 43 72 65 61 74 65 20 6d 65 74  .the xCreate met
7220: 68 6f 64 20 77 61 73 20 6e 6f 74 20 63 68 65 63  hod was not chec
7230: 6b 65 64 20 66 6f 72 20 6e 75 6c 6c 2e 0a 0a 3c  ked for null...<
7240: 2f 70 3e 3c 70 3e 0a 49 66 20 74 68 65 20 78 43  /p><p>.If the xC
7250: 72 65 61 74 65 20 6d 65 74 68 6f 64 20 69 73 20  reate method is 
7260: 74 68 65 20 65 78 61 63 74 20 73 61 6d 65 20 70  the exact same p
7270: 6f 69 6e 74 65 72 20 61 73 20 74 68 65 20 3c 61  ointer as the <a
7280: 20 68 72 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c   href="vtab.html
7290: 23 78 63 6f 6e 6e 65 63 74 22 3e 78 43 6f 6e 6e  #xconnect">xConn
72a0: 65 63 74 3c 2f 61 3e 20 6d 65 74 68 6f 64 2c 0a  ect</a> method,.
72b0: 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74  that indicates t
72c0: 68 61 74 20 74 68 65 20 76 69 72 74 75 61 6c 20  hat the virtual 
72d0: 74 61 62 6c 65 20 64 6f 65 73 20 6e 6f 74 20 6e  table does not n
72e0: 65 65 64 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  eed to initializ
72f0: 65 20 62 61 63 6b 69 6e 67 0a 73 74 6f 72 65 2e  e backing.store.
7300: 20 20 53 75 63 68 20 61 20 76 69 72 74 75 61 6c    Such a virtual
7310: 20 74 61 62 6c 65 20 63 61 6e 20 62 65 20 75 73   table can be us
7320: 65 64 20 61 73 20 61 6e 20 3c 61 20 68 72 65 66  ed as an <a href
7330: 3d 22 76 74 61 62 2e 68 74 6d 6c 23 65 70 6f 76  ="vtab.html#epov
7340: 74 61 62 22 3e 65 70 6f 6e 79 6d 6f 75 73 20 76  tab">eponymous v
7350: 69 72 74 75 61 6c 20 74 61 62 6c 65 3c 2f 61 3e  irtual table</a>
7360: 0a 6f 72 20 61 73 20 61 20 6e 61 6d 65 64 20 76  .or as a named v
7370: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 75 73 69  irtual table usi
7380: 6e 67 20 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67  ng <a href="lang
7390: 5f 63 72 65 61 74 65 76 74 61 62 2e 68 74 6d 6c  _createvtab.html
73a0: 22 3e 43 52 45 41 54 45 20 56 49 52 54 55 41 4c  ">CREATE VIRTUAL
73b0: 20 54 41 42 4c 45 3c 2f 61 3e 20 6f 72 20 62 6f   TABLE</a> or bo
73c0: 74 68 2e 0a 0a 3c 61 20 6e 61 6d 65 3d 22 68 69  th...<a name="hi
73d0: 64 64 65 6e 63 6f 6c 22 3e 3c 2f 61 3e 0a 0a 3c  ddencol"></a>..<
73e0: 2f 70 3e 3c 68 33 20 69 64 3d 22 68 69 64 64 65  /p><h3 id="hidde
73f0: 6e 5f 63 6f 6c 75 6d 6e 73 5f 69 6e 5f 76 69 72  n_columns_in_vir
7400: 74 75 61 6c 5f 74 61 62 6c 65 73 22 3e 3c 73 70  tual_tables"><sp
7410: 61 6e 3e 32 2e 31 2e 31 2e 20 3c 2f 73 70 61 6e  an>2.1.1. </span
7420: 3e 48 69 64 64 65 6e 20 63 6f 6c 75 6d 6e 73 20  >Hidden columns 
7430: 69 6e 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  in virtual table
7440: 73 3c 2f 68 33 3e 0a 3c 70 3e 49 66 20 61 20 63  s</h3>.<p>If a c
7450: 6f 6c 75 6d 6e 20 64 61 74 61 74 79 70 65 20 63  olumn datatype c
7460: 6f 6e 74 61 69 6e 73 20 74 68 65 20 73 70 65 63  ontains the spec
7470: 69 61 6c 20 6b 65 79 77 6f 72 64 20 22 48 49 44  ial keyword "HID
7480: 44 45 4e 22 0a 28 69 6e 20 61 6e 79 20 63 6f 6d  DEN".(in any com
7490: 62 69 6e 61 74 69 6f 6e 20 6f 66 20 75 70 70 65  bination of uppe
74a0: 72 20 61 6e 64 20 6c 6f 77 65 72 20 63 61 73 65  r and lower case
74b0: 20 6c 65 74 74 65 72 73 29 20 74 68 65 6e 20 74   letters) then t
74c0: 68 61 74 20 6b 65 79 77 6f 72 64 0a 69 74 20 69  hat keyword.it i
74d0: 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
74e0: 68 65 20 63 6f 6c 75 6d 6e 20 64 61 74 61 74 79  he column dataty
74f0: 70 65 20 6e 61 6d 65 20 61 6e 64 20 74 68 65 20  pe name and the 
7500: 63 6f 6c 75 6d 6e 20 69 73 20 6d 61 72 6b 65 64  column is marked
7510: 20 0a 61 73 20 61 20 68 69 64 64 65 6e 20 63 6f   .as a hidden co
7520: 6c 75 6d 6e 20 69 6e 74 65 72 6e 61 6c 6c 79 2e  lumn internally.
7530: 20 0a 41 20 68 69 64 64 65 6e 20 63 6f 6c 75 6d   .A hidden colum
7540: 6e 20 64 69 66 66 65 72 73 20 66 72 6f 6d 20 61  n differs from a
7550: 20 6e 6f 72 6d 61 6c 20 63 6f 6c 75 6d 6e 20 69   normal column i
7560: 6e 20 74 68 72 65 65 20 72 65 73 70 65 63 74 73  n three respects
7570: 3a 0a 0a 3c 2f 70 3e 3c 70 3e 0a 3c 2f 70 3e 3c  :..</p><p>.</p><
7580: 75 6c 3e 0a 3c 6c 69 3e 20 48 69 64 64 65 6e 20  ul>.<li> Hidden 
7590: 63 6f 6c 75 6d 6e 73 20 61 72 65 20 6e 6f 74 20  columns are not 
75a0: 6c 69 73 74 65 64 20 69 6e 20 74 68 65 20 64 61  listed in the da
75b0: 74 61 73 65 74 20 72 65 74 75 72 6e 65 64 20 62  taset returned b
75c0: 79 20 0a 20 20 20 20 20 22 3c 61 20 68 72 65 66  y .     "<a href
75d0: 3d 22 70 72 61 67 6d 61 2e 68 74 6d 6c 23 70 72  ="pragma.html#pr
75e0: 61 67 6d 61 5f 74 61 62 6c 65 5f 69 6e 66 6f 22  agma_table_info"
75f0: 3e 50 52 41 47 4d 41 20 74 61 62 6c 65 5f 69 6e  >PRAGMA table_in
7600: 66 6f 3c 2f 61 3e 22 2c 0a 3c 2f 6c 69 3e 3c 6c  fo</a>",.</li><l
7610: 69 3e 20 48 69 64 64 65 6e 20 63 6f 6c 75 6d 6e  i> Hidden column
7620: 73 20 61 72 65 20 6e 6f 74 20 69 6e 63 6c 75 64  s are not includ
7630: 65 64 20 69 6e 20 74 68 65 20 65 78 70 61 6e 73  ed in the expans
7640: 69 6f 6e 20 6f 66 20 61 20 22 2a 22 0a 20 20 20  ion of a "*".   
7650: 20 20 65 78 70 72 65 73 73 69 6f 6e 20 69 6e 20    expression in 
7660: 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
7670: 66 20 61 20 3c 61 20 68 72 65 66 3d 22 6c 61 6e  f a <a href="lan
7680: 67 5f 73 65 6c 65 63 74 2e 68 74 6d 6c 22 3e 53  g_select.html">S
7690: 45 4c 45 43 54 3c 2f 61 3e 2c 20 61 6e 64 0a 3c  ELECT</a>, and.<
76a0: 2f 6c 69 3e 3c 6c 69 3e 20 48 69 64 64 65 6e 20  /li><li> Hidden 
76b0: 63 6f 6c 75 6d 6e 73 20 61 72 65 20 6e 6f 74 20  columns are not 
76c0: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
76d0: 69 6d 70 6c 69 63 69 74 20 63 6f 6c 75 6d 6e 2d  implicit column-
76e0: 6c 69 73 74 20 0a 20 20 20 20 20 75 73 65 64 20  list .     used 
76f0: 62 79 20 61 6e 20 3c 61 20 68 72 65 66 3d 22 6c  by an <a href="l
7700: 61 6e 67 5f 69 6e 73 65 72 74 2e 68 74 6d 6c 22  ang_insert.html"
7710: 3e 49 4e 53 45 52 54 3c 2f 61 3e 20 73 74 61 74  >INSERT</a> stat
7720: 65 6d 65 6e 74 20 74 68 61 74 20 6c 61 63 6b 73  ement that lacks
7730: 20 61 6e 20 65 78 70 6c 69 63 69 74 20 63 6f 6c   an explicit col
7740: 75 6d 6e 2d 6c 69 73 74 2e 20 0a 3c 2f 6c 69 3e  umn-list. .</li>
7750: 3c 2f 75 6c 3e 0a 0a 3c 70 3e 46 6f 72 20 65 78  </ul>..<p>For ex
7760: 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 66 6f  ample, if the fo
7770: 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 69 73 20 70  llowing SQL is p
7780: 61 73 73 65 64 20 74 6f 20 3c 61 20 68 72 65 66  assed to <a href
7790: 3d 22 63 33 72 65 66 2f 64 65 63 6c 61 72 65 5f  ="c3ref/declare_
77a0: 76 74 61 62 2e 68 74 6d 6c 22 3e 73 71 6c 69 74  vtab.html">sqlit
77b0: 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28  e3_declare_vtab(
77c0: 29 3c 2f 61 3e 3a 0a 0a 3c 2f 70 3e 3c 64 69 76  )</a>:..</p><div
77d0: 20 63 6c 61 73 73 3d 22 63 6f 64 65 62 6c 6f 63   class="codebloc
77e0: 6b 22 3e 3c 70 72 65 3e 43 52 45 41 54 45 20 54  k"><pre>CREATE T
77f0: 41 42 4c 45 20 78 28 61 20 48 49 44 44 45 4e 20  ABLE x(a HIDDEN 
7800: 56 41 52 43 48 41 52 28 31 32 29 2c 20 62 20 49  VARCHAR(12), b I
7810: 4e 54 45 47 45 52 2c 20 63 20 49 4e 54 45 47 45  NTEGER, c INTEGE
7820: 52 20 48 69 64 64 65 6e 29 3b 0a 3c 2f 70 72 65  R Hidden);.</pre
7830: 3e 3c 2f 64 69 76 3e 0a 0a 3c 70 3e 54 68 65 6e  ></div>..<p>Then
7840: 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
7850: 6c 65 20 77 6f 75 6c 64 20 62 65 20 63 72 65 61  le would be crea
7860: 74 65 64 20 77 69 74 68 20 74 77 6f 20 68 69 64  ted with two hid
7870: 64 65 6e 20 63 6f 6c 75 6d 6e 73 2c 0a 61 6e 64  den columns,.and
7880: 20 77 69 74 68 20 64 61 74 61 74 79 70 65 73 20   with datatypes 
7890: 6f 66 20 22 56 41 52 43 48 41 52 28 31 32 29 22  of "VARCHAR(12)"
78a0: 20 61 6e 64 20 22 49 4e 54 45 47 45 52 22 2e 0a   and "INTEGER"..
78b0: 0a 3c 2f 70 3e 3c 70 3e 41 6e 20 65 78 61 6d 70  .</p><p>An examp
78c0: 6c 65 20 75 73 65 20 6f 66 20 68 69 64 64 65 6e  le use of hidden
78d0: 20 63 6f 6c 75 6d 6e 73 20 63 61 6e 20 62 65 20   columns can be 
78e0: 73 65 65 6e 20 69 6e 20 74 68 65 20 3c 61 20 68  seen in the <a h
78f0: 72 65 66 3d 22 66 74 73 33 2e 68 74 6d 6c 22 3e  ref="fts3.html">
7900: 46 54 53 33 3c 2f 61 3e 20 76 69 72 74 75 61 6c  FTS3</a> virtual
7910: 20 0a 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e   .table implemen
7920: 74 61 74 69 6f 6e 2c 20 77 68 65 72 65 20 65 76  tation, where ev
7930: 65 72 79 20 46 54 53 20 76 69 72 74 75 61 6c 20  ery FTS virtual 
7940: 74 61 62 6c 65 0a 63 6f 6e 74 61 69 6e 73 20 61  table.contains a
7950: 6e 20 3c 61 20 68 72 65 66 3d 22 66 74 73 33 2e  n <a href="fts3.
7960: 68 74 6d 6c 23 68 69 64 64 65 6e 63 6f 6c 22 3e  html#hiddencol">
7970: 46 54 53 20 68 69 64 64 65 6e 20 63 6f 6c 75 6d  FTS hidden colum
7980: 6e 3c 2f 61 3e 20 74 68 61 74 20 69 73 20 75 73  n</a> that is us
7990: 65 64 20 74 6f 20 70 61 73 73 20 69 6e 66 6f 72  ed to pass infor
79a0: 6d 61 74 69 6f 6e 20 66 72 6f 6d 20 74 68 65 0a  mation from the.
79b0: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e  virtual table in
79c0: 74 6f 20 3c 61 20 68 72 65 66 3d 22 66 74 73 33  to <a href="fts3
79d0: 2e 68 74 6d 6c 23 73 6e 69 70 70 65 74 22 3e 46  .html#snippet">F
79e0: 54 53 20 61 75 78 69 6c 69 61 72 79 20 66 75 6e  TS auxiliary fun
79f0: 63 74 69 6f 6e 73 3c 2f 61 3e 20 61 6e 64 20 74  ctions</a> and t
7a00: 6f 20 74 68 65 20 3c 61 20 68 72 65 66 3d 22 66  o the <a href="f
7a10: 74 73 33 2e 68 74 6d 6c 23 66 75 6c 6c 5f 74 65  ts3.html#full_te
7a20: 78 74 5f 69 6e 64 65 78 5f 71 75 65 72 69 65 73  xt_index_queries
7a30: 22 3e 46 54 53 20 4d 41 54 43 48 3c 2f 61 3e 20  ">FTS MATCH</a> 
7a40: 6f 70 65 72 61 74 6f 72 2e 0a 0a 3c 61 20 6e 61  operator...<a na
7a50: 6d 65 3d 22 74 61 62 66 75 6e 63 32 22 3e 3c 2f  me="tabfunc2"></
7a60: 61 3e 0a 0a 3c 2f 70 3e 3c 68 33 20 69 64 3d 22  a>..</p><h3 id="
7a70: 74 61 62 6c 65 5f 76 61 6c 75 65 64 5f 66 75 6e  table_valued_fun
7a80: 63 74 69 6f 6e 73 22 3e 3c 73 70 61 6e 3e 32 2e  ctions"><span>2.
7a90: 31 2e 32 2e 20 3c 2f 73 70 61 6e 3e 54 61 62 6c  1.2. </span>Tabl
7aa0: 65 2d 76 61 6c 75 65 64 20 66 75 6e 63 74 69 6f  e-valued functio
7ab0: 6e 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 41 20 3c 61  ns</h3>..<p>A <a
7ac0: 20 68 72 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c   href="vtab.html
7ad0: 22 3e 76 69 72 74 75 61 6c 20 74 61 62 6c 65 3c  ">virtual table<
7ae0: 2f 61 3e 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  /a> that contain
7af0: 73 20 3c 61 20 68 72 65 66 3d 22 76 74 61 62 2e  s <a href="vtab.
7b00: 68 74 6d 6c 23 68 69 64 64 65 6e 63 6f 6c 22 3e  html#hiddencol">
7b10: 68 69 64 64 65 6e 20 63 6f 6c 75 6d 6e 73 3c 2f  hidden columns</
7b20: 61 3e 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c  a> can be used l
7b30: 69 6b 65 0a 61 20 74 61 62 6c 65 2d 76 61 6c 75  ike.a table-valu
7b40: 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 6e 20 74  ed function in t
7b50: 68 65 20 46 52 4f 4d 20 63 6c 61 75 73 65 20 6f  he FROM clause o
7b60: 66 20 61 20 3c 61 20 68 72 65 66 3d 22 6c 61 6e  f a <a href="lan
7b70: 67 5f 73 65 6c 65 63 74 2e 68 74 6d 6c 22 3e 53  g_select.html">S
7b80: 45 4c 45 43 54 3c 2f 61 3e 20 73 74 61 74 65 6d  ELECT</a> statem
7b90: 65 6e 74 2e 0a 54 68 65 20 61 72 67 75 6d 65 6e  ent..The argumen
7ba0: 74 73 20 74 6f 20 74 68 65 20 74 61 62 6c 65 2d  ts to the table-
7bb0: 76 61 6c 75 65 64 20 66 75 6e 63 74 69 6f 6e 20  valued function 
7bc0: 62 65 63 6f 6d 65 20 63 6f 6e 73 74 72 61 69 6e  become constrain
7bd0: 74 73 20 6f 6e 20 0a 74 68 65 20 48 49 44 44 45  ts on .the HIDDE
7be0: 4e 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 74 68 65  N columns of the
7bf0: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 0a   virtual table..
7c00: 0a 3c 2f 70 3e 3c 70 3e 46 6f 72 20 65 78 61 6d  .</p><p>For exam
7c10: 70 6c 65 2c 20 74 68 65 20 22 67 65 6e 65 72 61  ple, the "genera
7c20: 74 65 5f 73 65 72 69 65 73 22 20 65 78 74 65 6e  te_series" exten
7c30: 73 69 6f 6e 20 28 6c 6f 63 61 74 65 64 20 69 6e  sion (located in
7c40: 20 74 68 65 0a 3c 61 20 68 72 65 66 3d 22 68 74   the.<a href="ht
7c50: 74 70 3a 2f 2f 77 77 77 2e 73 71 6c 69 74 65 2e  tp://www.sqlite.
7c60: 6f 72 67 2f 73 72 63 2f 61 72 74 69 66 61 63 74  org/src/artifact
7c70: 3f 63 69 3d 74 72 75 6e 6b 26 66 69 6c 65 6e 61  ?ci=trunk&filena
7c80: 6d 65 3d 65 78 74 2f 6d 69 73 63 2f 73 65 72 69  me=ext/misc/seri
7c90: 65 73 2e 63 22 3e 65 78 74 2f 6d 69 73 63 2f 73  es.c">ext/misc/s
7ca0: 65 72 69 65 73 2e 63 3c 2f 61 3e 0a 66 69 6c 65  eries.c</a>.file
7cb0: 20 69 6e 20 74 68 65 20 3c 61 20 68 72 65 66 3d   in the <a href=
7cc0: 22 68 74 74 70 3a 2f 2f 77 77 77 2e 73 71 6c 69  "http://www.sqli
7cd0: 74 65 2e 6f 72 67 2f 73 72 63 2f 74 72 65 65 3f  te.org/src/tree?
7ce0: 63 69 3d 74 72 75 6e 6b 22 3e 73 6f 75 72 63 65  ci=trunk">source
7cf0: 20 74 72 65 65 3c 2f 61 3e 29 0a 69 6d 70 6c 65   tree</a>).imple
7d00: 6d 65 6e 74 73 20 61 6e 20 3c 61 20 68 72 65 66  ments an <a href
7d10: 3d 22 76 74 61 62 2e 68 74 6d 6c 23 65 70 6f 76  ="vtab.html#epov
7d20: 74 61 62 22 3e 65 70 6f 6e 79 6d 6f 75 73 20 76  tab">eponymous v
7d30: 69 72 74 75 61 6c 20 74 61 62 6c 65 3c 2f 61 3e  irtual table</a>
7d40: 20 77 69 74 68 20 74 68 65 20 66 6f 6c 6c 6f 77   with the follow
7d50: 69 6e 67 20 73 63 68 65 6d 61 3a 0a 0a 3c 2f 70  ing schema:..</p
7d60: 3e 3c 64 69 76 20 63 6c 61 73 73 3d 22 63 6f 64  ><div class="cod
7d70: 65 62 6c 6f 63 6b 22 3e 3c 70 72 65 3e 43 52 45  eblock"><pre>CRE
7d80: 41 54 45 20 54 41 42 4c 45 20 67 65 6e 65 72 61  ATE TABLE genera
7d90: 74 65 5f 73 65 72 69 65 73 28 0a 20 20 76 61 6c  te_series(.  val
7da0: 75 65 2c 0a 20 20 73 74 61 72 74 20 48 49 44 44  ue,.  start HIDD
7db0: 45 4e 2c 0a 20 20 73 74 6f 70 20 48 49 44 44 45  EN,.  stop HIDDE
7dc0: 4e 2c 0a 20 20 73 74 65 70 20 48 49 44 44 45 4e  N,.  step HIDDEN
7dd0: 0a 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 64 69 76 3e  .);.</pre></div>
7de0: 0a 0a 3c 70 3e 54 68 65 20 3c 61 20 68 72 65 66  ..<p>The <a href
7df0: 3d 22 76 74 61 62 2e 68 74 6d 6c 23 78 62 65 73  ="vtab.html#xbes
7e00: 74 69 6e 64 65 78 22 3e 73 71 6c 69 74 65 33 5f  tindex">sqlite3_
7e10: 6d 6f 64 75 6c 65 2e 78 42 65 73 74 49 6e 64 65  module.xBestInde
7e20: 78 3c 2f 61 3e 20 6d 65 74 68 6f 64 20 69 6e 20  x</a> method in 
7e30: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
7e40: 6f 6e 20 6f 66 20 74 68 69 73 0a 74 61 62 6c 65  on of this.table
7e50: 20 63 68 65 63 6b 73 20 66 6f 72 20 65 71 75 61   checks for equa
7e60: 6c 69 74 79 20 63 6f 6e 73 74 72 61 69 6e 74 73  lity constraints
7e70: 20 61 67 61 69 6e 73 74 20 74 68 65 20 48 49 44   against the HID
7e80: 44 45 4e 20 63 6f 6c 75 6d 6e 73 2c 20 61 6e 64  DEN columns, and
7e90: 20 75 73 65 73 0a 74 68 6f 73 65 20 61 73 20 69   uses.those as i
7ea0: 6e 70 75 74 20 70 61 72 61 6d 65 74 65 72 73 20  nput parameters 
7eb0: 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  to determine the
7ec0: 20 72 61 6e 67 65 20 6f 66 20 69 6e 74 65 67 65   range of intege
7ed0: 72 20 22 76 61 6c 75 65 22 20 6f 75 74 70 75 74  r "value" output
7ee0: 73 0a 74 6f 20 67 65 6e 65 72 61 74 65 2e 20 20  s.to generate.  
7ef0: 52 65 61 73 6f 6e 61 62 6c 65 20 64 65 66 61 75  Reasonable defau
7f00: 6c 74 73 20 61 72 65 20 75 73 65 64 20 66 6f 72  lts are used for
7f10: 20 61 6e 79 20 75 6e 63 6f 6e 73 74 72 61 69 6e   any unconstrain
7f20: 65 64 20 63 6f 6c 75 6d 6e 73 2e 0a 46 6f 72 20  ed columns..For 
7f30: 65 78 61 6d 70 6c 65 2c 20 74 6f 20 6c 69 73 74  example, to list
7f40: 20 61 6c 6c 20 69 6e 74 65 67 65 72 73 20 62 65   all integers be
7f50: 74 77 65 65 6e 20 35 20 61 6e 64 20 35 30 3a 0a  tween 5 and 50:.
7f60: 0a 3c 2f 70 3e 3c 64 69 76 20 63 6c 61 73 73 3d  .</p><div class=
7f70: 22 63 6f 64 65 62 6c 6f 63 6b 22 3e 3c 70 72 65  "codeblock"><pre
7f80: 3e 53 45 4c 45 43 54 20 76 61 6c 75 65 20 46 52  >SELECT value FR
7f90: 4f 4d 20 67 65 6e 65 72 61 74 65 5f 73 65 72 69  OM generate_seri
7fa0: 65 73 28 35 2c 35 30 29 3b 0a 3c 2f 70 72 65 3e  es(5,50);.</pre>
7fb0: 3c 2f 64 69 76 3e 0a 0a 3c 70 3e 54 68 65 20 70  </div>..<p>The p
7fc0: 72 65 76 69 6f 75 73 20 71 75 65 72 79 20 69 73  revious query is
7fd0: 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 74   equivalent to t
7fe0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 3a 0a 0a 3c  he following:..<
7ff0: 2f 70 3e 3c 64 69 76 20 63 6c 61 73 73 3d 22 63  /p><div class="c
8000: 6f 64 65 62 6c 6f 63 6b 22 3e 3c 70 72 65 3e 53  odeblock"><pre>S
8010: 45 4c 45 43 54 20 76 61 6c 75 65 20 46 52 4f 4d  ELECT value FROM
8020: 20 67 65 6e 65 72 61 74 65 5f 73 65 72 69 65 73   generate_series
8030: 20 57 48 45 52 45 20 73 74 61 72 74 3d 35 20 41   WHERE start=5 A
8040: 4e 44 20 73 74 6f 70 3d 35 30 3b 0a 3c 2f 70 72  ND stop=50;.</pr
8050: 65 3e 3c 2f 64 69 76 3e 0a 0a 3c 70 3e 41 72 67  e></div>..<p>Arg
8060: 75 6d 65 6e 74 73 20 6f 6e 20 74 68 65 20 76 69  uments on the vi
8070: 72 74 75 61 6c 20 74 61 62 6c 65 20 6e 61 6d 65  rtual table name
8080: 20 61 72 65 20 6d 61 74 63 68 65 64 20 74 6f 20   are matched to 
8090: 3c 61 20 68 72 65 66 3d 22 76 74 61 62 2e 68 74  <a href="vtab.ht
80a0: 6d 6c 23 68 69 64 64 65 6e 63 6f 6c 22 3e 68 69  ml#hiddencol">hi
80b0: 64 64 65 6e 20 63 6f 6c 75 6d 6e 73 3c 2f 61 3e  dden columns</a>
80c0: 0a 69 6e 20 6f 72 64 65 72 2e 20 20 54 68 65 20  .in order.  The 
80d0: 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
80e0: 6e 74 73 20 63 61 6e 20 62 65 20 6c 65 73 73 20  nts can be less 
80f0: 74 68 61 6e 20 74 68 65 0a 6e 75 6d 62 65 72 20  than the.number 
8100: 6f 66 20 68 69 64 64 65 6e 20 63 6f 6c 75 6d 6e  of hidden column
8110: 73 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  s, in which case
8120: 20 74 68 65 20 6c 61 74 74 65 72 20 68 69 64 64   the latter hidd
8130: 65 6e 20 63 6f 6c 75 6d 6e 73 20 61 72 65 0a 75  en columns are.u
8140: 6e 63 6f 6e 73 74 72 61 69 6e 65 64 2e 20 20 48  nconstrained.  H
8150: 6f 77 65 76 65 72 2c 20 61 6e 20 65 72 72 6f 72  owever, an error
8160: 20 72 65 73 75 6c 74 73 20 69 66 20 74 68 65 72   results if ther
8170: 65 20 61 72 65 20 6d 6f 72 65 20 61 72 67 75 6d  e are more argum
8180: 65 6e 74 73 0a 74 68 61 6e 20 74 68 65 72 65 20  ents.than there 
8190: 61 72 65 20 68 69 64 64 65 6e 20 63 6f 6c 75 6d  are hidden colum
81a0: 6e 73 20 69 6e 20 74 68 65 20 76 69 72 74 75 61  ns in the virtua
81b0: 6c 20 74 61 62 6c 65 2e 0a 0a 3c 61 20 6e 61 6d  l table...<a nam
81c0: 65 3d 22 77 6f 72 69 64 22 3e 3c 2f 61 3e 0a 0a  e="worid"></a>..
81d0: 3c 2f 70 3e 3c 68 33 20 69 64 3d 22 5f 77 69 74  </p><h3 id="_wit
81e0: 68 6f 75 74 5f 72 6f 77 69 64 5f 76 69 72 74 75  hout_rowid_virtu
81f0: 61 6c 5f 74 61 62 6c 65 73 5f 22 3e 3c 73 70 61  al_tables_"><spa
8200: 6e 3e 32 2e 31 2e 33 2e 20 3c 2f 73 70 61 6e 3e  n>2.1.3. </span>
8210: 20 57 49 54 48 4f 55 54 20 52 4f 57 49 44 20 56   WITHOUT ROWID V
8220: 69 72 74 75 61 6c 20 54 61 62 6c 65 73 20 3c 2f  irtual Tables </
8230: 68 33 3e 0a 0a 3c 70 3e 42 65 67 69 6e 6e 69 6e  h3>..<p>Beginnin
8240: 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 3c 61  g with SQLite <a
8250: 20 68 72 65 66 3d 22 72 65 6c 65 61 73 65 6c 6f   href="releaselo
8260: 67 2f 33 5f 31 34 2e 68 74 6d 6c 22 3e 76 65 72  g/3_14.html">ver
8270: 73 69 6f 6e 20 33 2e 31 34 2e 30 3c 2f 61 3e 20  sion 3.14.0</a> 
8280: 28 32 30 31 36 2d 30 38 2d 30 38 29 2c 20 0a 74  (2016-08-08), .t
8290: 68 65 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  he CREATE TABLE 
82a0: 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 69  statement that.i
82b0: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 3c 61  s passed into <a
82c0: 20 68 72 65 66 3d 22 63 33 72 65 66 2f 64 65 63   href="c3ref/dec
82d0: 6c 61 72 65 5f 76 74 61 62 2e 68 74 6d 6c 22 3e  lare_vtab.html">
82e0: 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f  sqlite3_declare_
82f0: 76 74 61 62 28 29 3c 2f 61 3e 20 6d 61 79 20 63  vtab()</a> may c
8300: 6f 6e 74 61 69 6e 20 61 20 3c 61 20 68 72 65 66  ontain a <a href
8310: 3d 22 77 69 74 68 6f 75 74 72 6f 77 69 64 2e 68  ="withoutrowid.h
8320: 74 6d 6c 22 3e 57 49 54 48 4f 55 54 20 52 4f 57  tml">WITHOUT ROW
8330: 49 44 3c 2f 61 3e 20 63 6c 61 75 73 65 2e 0a 54  ID</a> clause..T
8340: 68 69 73 20 69 73 20 75 73 65 66 75 6c 20 66 6f  his is useful fo
8350: 72 20 63 61 73 65 73 20 77 68 65 72 65 20 74 68  r cases where th
8360: 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
8370: 72 6f 77 73 20 0a 63 61 6e 6e 6f 74 20 65 61 73  rows .cannot eas
8380: 69 6c 79 20 62 65 20 6d 61 70 70 65 64 20 69 6e  ily be mapped in
8390: 74 6f 20 75 6e 69 71 75 65 20 69 6e 74 65 67 65  to unique intege
83a0: 72 73 2e 20 20 41 20 43 52 45 41 54 45 20 54 41  rs.  A CREATE TA
83b0: 42 4c 45 0a 73 74 61 74 65 6d 65 6e 74 20 74 68  BLE.statement th
83c0: 61 74 20 69 6e 63 6c 75 64 65 73 20 57 49 54 48  at includes WITH
83d0: 4f 55 54 20 52 4f 57 49 44 20 6d 75 73 74 20 64  OUT ROWID must d
83e0: 65 66 69 6e 65 20 6f 6e 65 20 6f 72 20 6d 6f 72  efine one or mor
83f0: 65 20 63 6f 6c 75 6d 6e 73 20 61 73 0a 74 68 65  e columns as.the
8400: 20 50 52 49 4d 41 52 59 20 4b 45 59 2e 20 20 45   PRIMARY KEY.  E
8410: 76 65 72 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  very column of t
8420: 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59 20 6d  he PRIMARY KEY m
8430: 75 73 74 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ust individually
8440: 20 62 65 0a 4e 4f 54 20 4e 55 4c 4c 20 61 6e 64   be.NOT NULL and
8450: 20 61 6c 6c 20 63 6f 6c 75 6d 6e 73 20 66 6f 72   all columns for
8460: 20 65 61 63 68 20 72 6f 77 20 6d 75 73 74 20 62   each row must b
8470: 65 20 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 75  e collectively u
8480: 6e 69 71 75 65 2e 0a 0a 3c 2f 70 3e 3c 70 3e 4e  nique...</p><p>N
8490: 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ote that SQLite 
84a0: 64 6f 65 73 20 6e 6f 74 20 65 6e 66 6f 72 63 65  does not enforce
84b0: 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59   the PRIMARY KEY
84c0: 20 66 6f 72 20 61 20 57 49 54 48 4f 55 54 20 52   for a WITHOUT R
84d0: 4f 57 49 44 0a 76 69 72 74 75 61 6c 20 74 61 62  OWID.virtual tab
84e0: 6c 65 2e 20 20 45 6e 66 6f 72 63 65 6d 65 6e 74  le.  Enforcement
84f0: 20 69 73 20 74 68 65 20 72 65 73 70 6f 6e 73 69   is the responsi
8500: 62 69 6c 69 74 79 20 6f 66 20 74 68 65 20 75 6e  bility of the un
8510: 64 65 72 6c 79 69 6e 67 0a 76 69 72 74 75 61 6c  derlying.virtual
8520: 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
8530: 61 74 69 6f 6e 2e 20 20 42 75 74 20 53 51 4c 69  ation.  But SQLi
8540: 74 65 20 64 6f 65 73 20 61 73 73 75 6d 65 20 74  te does assume t
8550: 68 61 74 20 74 68 65 20 50 52 49 4d 41 52 59 20  hat the PRIMARY 
8560: 4b 45 59 0a 63 6f 6e 73 74 72 61 69 6e 74 20 69  KEY.constraint i
8570: 73 20 76 61 6c 69 64 20 2d 20 74 68 61 74 20 74  s valid - that t
8580: 68 65 20 69 64 65 6e 74 69 66 69 65 64 20 63 6f  he identified co
8590: 6c 75 6d 6e 73 20 72 65 61 6c 6c 79 20 61 72 65  lumns really are
85a0: 20 55 4e 49 51 55 45 20 61 6e 64 0a 4e 4f 54 20   UNIQUE and.NOT 
85b0: 4e 55 4c 4c 20 2d 20 61 6e 64 20 69 74 20 75 73  NULL - and it us
85c0: 65 73 20 74 68 61 74 20 61 73 73 75 6d 70 74 69  es that assumpti
85d0: 6f 6e 20 74 6f 20 6f 70 74 69 6d 69 7a 65 20 71  on to optimize q
85e0: 75 65 72 69 65 73 20 61 67 61 69 6e 73 74 20 74  ueries against t
85f0: 68 65 0a 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he.virtual table
8600: 2e 0a 0a 3c 2f 70 3e 3c 70 3e 54 68 65 20 72 6f  ...</p><p>The ro
8610: 77 69 64 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 6f  wid column is no
8620: 74 20 61 63 63 65 73 73 69 62 6c 65 20 6f 6e 20  t accessible on 
8630: 61 0a 57 49 54 48 4f 55 54 20 52 4f 57 49 44 20  a.WITHOUT ROWID 
8640: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 28 6f  virtual table (o
8650: 66 20 63 6f 75 72 73 65 29 2e 0a 0a 3c 2f 70 3e  f course)...</p>
8660: 3c 70 3e 54 68 65 20 3c 61 20 68 72 65 66 3d 22  <p>The <a href="
8670: 76 74 61 62 2e 68 74 6d 6c 23 78 75 70 64 61 74  vtab.html#xupdat
8680: 65 22 3e 78 55 70 64 61 74 65 3c 2f 61 3e 20 6d  e">xUpdate</a> m
8690: 65 74 68 6f 64 20 77 61 73 20 6f 72 69 67 69 6e  ethod was origin
86a0: 61 6c 6c 79 20 64 65 73 69 67 6e 65 64 20 61 72  ally designed ar
86b0: 6f 75 6e 64 20 68 61 76 69 6e 67 20 61 0a 3c 61  ound having a.<a
86c0: 20 68 72 65 66 3d 22 6c 61 6e 67 5f 63 72 65 61   href="lang_crea
86d0: 74 65 74 61 62 6c 65 2e 68 74 6d 6c 23 72 6f 77  tetable.html#row
86e0: 69 64 22 3e 52 4f 57 49 44 3c 2f 61 3e 20 61 73  id">ROWID</a> as
86f0: 20 61 20 73 69 6e 67 6c 65 20 76 61 6c 75 65 2e   a single value.
8700: 20 20 54 68 65 20 3c 61 20 68 72 65 66 3d 22 76    The <a href="v
8710: 74 61 62 2e 68 74 6d 6c 23 78 75 70 64 61 74 65  tab.html#xupdate
8720: 22 3e 78 55 70 64 61 74 65 3c 2f 61 3e 20 6d 65  ">xUpdate</a> me
8730: 74 68 6f 64 20 68 61 73 20 62 65 65 6e 20 65 78  thod has been ex
8740: 70 61 6e 64 65 64 20 74 6f 0a 61 63 63 6f 6d 6d  panded to.accomm
8750: 6f 64 61 74 65 20 61 6e 20 61 72 62 69 74 72 61  odate an arbitra
8760: 72 79 20 50 52 49 4d 41 52 59 20 4b 45 59 20 69  ry PRIMARY KEY i
8770: 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 52  n place of the R
8780: 4f 57 49 44 2c 20 62 75 74 20 74 68 65 0a 50 52  OWID, but the.PR
8790: 49 4d 41 52 59 20 4b 45 59 20 6d 75 73 74 20 73  IMARY KEY must s
87a0: 74 69 6c 6c 20 62 65 20 6f 6e 6c 79 20 6f 6e 65  till be only one
87b0: 20 63 6f 6c 75 6d 6e 2e 20 20 46 6f 72 20 74 68   column.  For th
87c0: 69 73 20 72 65 61 73 6f 6e 2c 20 53 51 4c 69 74  is reason, SQLit
87d0: 65 0a 77 69 6c 6c 20 72 65 6a 65 63 74 20 61 6e  e.will reject an
87e0: 79 20 57 49 54 48 4f 55 54 20 52 4f 57 49 44 20  y WITHOUT ROWID 
87f0: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 74 68  virtual table th
8800: 61 74 20 68 61 73 20 6d 6f 72 65 20 74 68 61 6e  at has more than
8810: 20 6f 6e 65 0a 50 52 49 4d 41 52 59 20 4b 45 59   one.PRIMARY KEY
8820: 20 63 6f 6c 75 6d 6e 20 61 6e 64 20 61 20 6e 6f   column and a no
8830: 6e 2d 4e 55 4c 4c 20 78 55 70 64 61 74 65 20 6d  n-NULL xUpdate m
8840: 65 74 68 6f 64 2e 0a 0a 3c 61 20 6e 61 6d 65 3d  ethod...<a name=
8850: 22 78 63 6f 6e 6e 65 63 74 22 3e 3c 2f 61 3e 0a  "xconnect"></a>.
8860: 0a 3c 2f 70 3e 3c 68 32 20 69 64 3d 22 74 68 65  .</p><h2 id="the
8870: 5f 78 63 6f 6e 6e 65 63 74 5f 6d 65 74 68 6f 64  _xconnect_method
8880: 22 3e 3c 73 70 61 6e 3e 32 2e 32 2e 20 3c 2f 73  "><span>2.2. </s
8890: 70 61 6e 3e 54 68 65 20 78 43 6f 6e 6e 65 63 74  pan>The xConnect
88a0: 20 4d 65 74 68 6f 64 3c 2f 68 32 3e 0a 0a 3c 64   Method</h2>..<d
88b0: 69 76 20 63 6c 61 73 73 3d 22 63 6f 64 65 62 6c  iv class="codebl
88c0: 6f 63 6b 22 3e 3c 70 72 65 3e 69 6e 74 20 28 2a  ock"><pre>int (*
88d0: 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65  xConnect)(sqlite
88e0: 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a  3*, void *pAux,.
88f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
8900: 20 61 72 67 63 2c 20 63 68 61 72 20 2a 2a 61 72   argc, char **ar
8910: 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  gv,.            
8920: 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a   sqlite3_vtab **
8930: 70 70 56 54 61 62 2c 0a 20 20 20 20 20 20 20 20  ppVTab,.        
8940: 20 20 20 20 20 63 68 61 72 20 2a 2a 70 7a 45 72       char **pzEr
8950: 72 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 64 69 76 3e  r);.</pre></div>
8960: 0a 0a 3c 70 3e 54 68 65 20 78 43 6f 6e 6e 65 63  ..<p>The xConnec
8970: 74 20 6d 65 74 68 6f 64 20 69 73 20 76 65 72 79  t method is very
8980: 20 73 69 6d 69 6c 61 72 20 74 6f 20 3c 61 20 68   similar to <a h
8990: 72 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23 78  ref="vtab.html#x
89a0: 63 72 65 61 74 65 22 3e 78 43 72 65 61 74 65 3c  create">xCreate<
89b0: 2f 61 3e 2e 20 0a 49 74 20 68 61 73 20 74 68 65  /a>. .It has the
89c0: 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72 73   same parameters
89d0: 20 61 6e 64 20 63 6f 6e 73 74 72 75 63 74 73 20   and constructs 
89e0: 61 20 6e 65 77 20 3c 61 20 68 72 65 66 3d 22 63  a new <a href="c
89f0: 33 72 65 66 2f 76 74 61 62 2e 68 74 6d 6c 22 3e  3ref/vtab.html">
8a00: 73 71 6c 69 74 65 33 5f 76 74 61 62 3c 2f 61 3e  sqlite3_vtab</a>
8a10: 20 73 74 72 75 63 74 75 72 65 20 0a 6a 75 73 74   structure .just
8a20: 20 6c 69 6b 65 20 78 43 72 65 61 74 65 2e 20 0a   like xCreate. .
8a30: 41 6e 64 20 69 74 20 6d 75 73 74 20 61 6c 73 6f  And it must also
8a40: 20 63 61 6c 6c 20 3c 61 20 68 72 65 66 3d 22 63   call <a href="c
8a50: 33 72 65 66 2f 64 65 63 6c 61 72 65 5f 76 74 61  3ref/declare_vta
8a60: 62 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f  b.html">sqlite3_
8a70: 64 65 63 6c 61 72 65 5f 76 74 61 62 28 29 3c 2f  declare_vtab()</
8a80: 61 3e 20 6c 69 6b 65 20 78 43 72 65 61 74 65 2e  a> like xCreate.
8a90: 0a 0a 3c 2f 70 3e 3c 70 3e 54 68 65 20 64 69 66  ..</p><p>The dif
8aa0: 66 65 72 65 6e 63 65 20 69 73 20 74 68 61 74 20  ference is that 
8ab0: 78 43 6f 6e 6e 65 63 74 20 69 73 20 63 61 6c 6c  xConnect is call
8ac0: 65 64 20 74 6f 20 65 73 74 61 62 6c 69 73 68 20  ed to establish 
8ad0: 61 20 6e 65 77 20 0a 63 6f 6e 6e 65 63 74 69 6f  a new .connectio
8ae0: 6e 20 74 6f 20 61 6e 20 65 78 69 73 74 69 6e 67  n to an existing
8af0: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 77   virtual table w
8b00: 68 65 72 65 61 73 20 78 43 72 65 61 74 65 20 69  hereas xCreate i
8b10: 73 20 63 61 6c 6c 65 64 20 0a 74 6f 20 63 72 65  s called .to cre
8b20: 61 74 65 20 61 20 6e 65 77 20 76 69 72 74 75 61  ate a new virtua
8b30: 6c 20 74 61 62 6c 65 20 66 72 6f 6d 20 73 63 72  l table from scr
8b40: 61 74 63 68 2e 0a 0a 3c 2f 70 3e 3c 70 3e 54 68  atch...</p><p>Th
8b50: 65 20 78 43 72 65 61 74 65 20 61 6e 64 20 78 43  e xCreate and xC
8b60: 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 73 20 61  onnect methods a
8b70: 72 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e  re only differen
8b80: 74 20 77 68 65 6e 20 74 68 65 0a 76 69 72 74 75  t when the.virtu
8b90: 61 6c 20 74 61 62 6c 65 20 68 61 73 20 73 6f 6d  al table has som
8ba0: 65 20 6b 69 6e 64 20 6f 66 20 62 61 63 6b 69 6e  e kind of backin
8bb0: 67 20 73 74 6f 72 65 20 74 68 61 74 20 6d 75 73  g store that mus
8bc0: 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
8bd0: 20 0a 74 68 65 20 66 69 72 73 74 20 74 69 6d 65   .the first time
8be0: 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
8bf0: 6c 65 20 69 73 20 63 72 65 61 74 65 64 2e 20 54  le is created. T
8c00: 68 65 20 78 43 72 65 61 74 65 20 6d 65 74 68 6f  he xCreate metho
8c10: 64 20 63 72 65 61 74 65 73 20 0a 61 6e 64 20 69  d creates .and i
8c20: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 62  nitializes the b
8c30: 61 63 6b 69 6e 67 20 73 74 6f 72 65 2e 20 54 68  acking store. Th
8c40: 65 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f  e xConnect metho
8c50: 64 20 6a 75 73 74 20 63 6f 6e 6e 65 63 74 73 20  d just connects 
8c60: 0a 74 6f 20 61 6e 20 65 78 69 73 74 69 6e 67 20  .to an existing 
8c70: 62 61 63 6b 69 6e 67 20 73 74 6f 72 65 2e 20 20  backing store.  
8c80: 57 68 65 6e 20 78 43 72 65 61 74 65 20 61 6e 64  When xCreate and
8c90: 20 78 43 6f 6e 6e 65 63 74 20 61 72 65 20 74 68   xConnect are th
8ca0: 65 20 73 61 6d 65 2c 0a 74 68 65 20 74 61 62 6c  e same,.the tabl
8cb0: 65 20 69 73 20 61 6e 20 3c 61 20 68 72 65 66 3d  e is an <a href=
8cc0: 22 76 74 61 62 2e 68 74 6d 6c 23 65 70 6f 76 74  "vtab.html#epovt
8cd0: 61 62 22 3e 65 70 6f 6e 79 6d 6f 75 73 20 76 69  ab">eponymous vi
8ce0: 72 74 75 61 6c 20 74 61 62 6c 65 3c 2f 61 3e 2e  rtual table</a>.
8cf0: 0a 0a 3c 2f 70 3e 3c 70 3e 41 73 20 61 6e 20 65  ..</p><p>As an e
8d00: 78 61 6d 70 6c 65 2c 20 63 6f 6e 73 69 64 65 72  xample, consider
8d10: 20 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65   a virtual table
8d20: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
8d30: 74 68 61 74 20 0a 70 72 6f 76 69 64 65 73 20 72  that .provides r
8d40: 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 20  ead-only access 
8d50: 74 6f 20 65 78 69 73 74 69 6e 67 20 63 6f 6d 6d  to existing comm
8d60: 61 2d 73 65 70 61 72 61 74 65 64 2d 76 61 6c 75  a-separated-valu
8d70: 65 20 28 43 53 56 29 0a 66 69 6c 65 73 20 6f 6e  e (CSV).files on
8d80: 20 64 69 73 6b 2e 20 54 68 65 72 65 20 69 73 20   disk. There is 
8d90: 6e 6f 20 62 61 63 6b 69 6e 67 20 73 74 6f 72 65  no backing store
8da0: 20 74 68 61 74 20 6e 65 65 64 73 20 74 6f 20 62   that needs to b
8db0: 65 20 63 72 65 61 74 65 64 20 0a 6f 72 20 69 6e  e created .or in
8dc0: 69 74 69 61 6c 69 7a 65 64 20 66 6f 72 20 73 75  itialized for su
8dd0: 63 68 20 61 20 76 69 72 74 75 61 6c 20 74 61 62  ch a virtual tab
8de0: 6c 65 20 28 73 69 6e 63 65 20 74 68 65 20 43 53  le (since the CS
8df0: 56 20 66 69 6c 65 73 20 61 6c 72 65 61 64 79 20  V files already 
8e00: 0a 65 78 69 73 74 20 6f 6e 20 64 69 73 6b 29 20  .exist on disk) 
8e10: 73 6f 20 74 68 65 20 78 43 72 65 61 74 65 20 61  so the xCreate a
8e20: 6e 64 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68  nd xConnect meth
8e30: 6f 64 73 20 77 69 6c 6c 20 62 65 20 69 64 65 6e  ods will be iden
8e40: 74 69 63 61 6c 20 0a 66 6f 72 20 74 68 61 74 20  tical .for that 
8e50: 6d 6f 64 75 6c 65 2e 0a 0a 3c 2f 70 3e 3c 70 3e  module...</p><p>
8e60: 41 6e 6f 74 68 65 72 20 65 78 61 6d 70 6c 65 20  Another example 
8e70: 69 73 20 61 20 76 69 72 74 75 61 6c 20 74 61 62  is a virtual tab
8e80: 6c 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  le that implemen
8e90: 74 73 20 61 20 66 75 6c 6c 2d 74 65 78 74 20 69  ts a full-text i
8ea0: 6e 64 65 78 2e 20 0a 54 68 65 20 78 43 72 65 61  ndex. .The xCrea
8eb0: 74 65 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 63  te method must c
8ec0: 72 65 61 74 65 20 61 6e 64 20 69 6e 69 74 69 61  reate and initia
8ed0: 6c 69 7a 65 20 64 61 74 61 20 73 74 72 75 63 74  lize data struct
8ee0: 75 72 65 73 20 74 6f 20 68 6f 6c 64 20 0a 74 68  ures to hold .th
8ef0: 65 20 64 69 63 74 69 6f 6e 61 72 79 20 61 6e 64  e dictionary and
8f00: 20 70 6f 73 74 69 6e 67 20 6c 69 73 74 73 20 66   posting lists f
8f10: 6f 72 20 74 68 61 74 20 69 6e 64 65 78 2e 20 54  or that index. T
8f20: 68 65 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68  he xConnect meth
8f30: 6f 64 2c 0a 6f 6e 20 74 68 65 20 6f 74 68 65 72  od,.on the other
8f40: 20 68 61 6e 64 2c 20 6f 6e 6c 79 20 68 61 73 20   hand, only has 
8f50: 74 6f 20 6c 6f 63 61 74 65 20 61 6e 64 20 75 73  to locate and us
8f60: 65 20 61 6e 20 65 78 69 73 74 69 6e 67 20 64 69  e an existing di
8f70: 63 74 69 6f 6e 61 72 79 20 0a 61 6e 64 20 70 6f  ctionary .and po
8f80: 73 74 69 6e 67 20 6c 69 73 74 73 20 74 68 61 74  sting lists that
8f90: 20 77 65 72 65 20 63 72 65 61 74 65 64 20 62 79   were created by
8fa0: 20 61 20 70 72 69 6f 72 20 78 43 72 65 61 74 65   a prior xCreate
8fb0: 20 63 61 6c 6c 2e 0a 0a 3c 2f 70 3e 3c 70 3e 54   call...</p><p>T
8fc0: 68 65 20 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68  he xConnect meth
8fd0: 6f 64 20 6d 75 73 74 20 72 65 74 75 72 6e 20 3c  od must return <
8fe0: 61 20 68 72 65 66 3d 22 72 65 73 63 6f 64 65 2e  a href="rescode.
8ff0: 68 74 6d 6c 23 6f 6b 22 3e 53 51 4c 49 54 45 5f  html#ok">SQLITE_
9000: 4f 4b 3c 2f 61 3e 20 69 66 20 69 74 20 69 73 20  OK</a> if it is 
9010: 73 75 63 63 65 73 73 66 75 6c 20 0a 69 6e 20 63  successful .in c
9020: 72 65 61 74 69 6e 67 20 74 68 65 20 6e 65 77 20  reating the new 
9030: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2c 20 6f  virtual table, o
9040: 72 20 3c 61 20 68 72 65 66 3d 22 72 65 73 63 6f  r <a href="resco
9050: 64 65 2e 68 74 6d 6c 23 65 72 72 6f 72 22 3e 53  de.html#error">S
9060: 51 4c 49 54 45 5f 45 52 52 4f 52 3c 2f 61 3e 20  QLITE_ERROR</a> 
9070: 69 66 20 69 74 20 69 73 20 6e 6f 74 20 0a 73 75  if it is not .su
9080: 63 63 65 73 73 66 75 6c 2e 20 49 66 20 6e 6f 74  ccessful. If not
9090: 20 73 75 63 63 65 73 73 66 75 6c 2c 20 74 68 65   successful, the
90a0: 20 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f   <a href="c3ref/
90b0: 76 74 61 62 2e 68 74 6d 6c 22 3e 73 71 6c 69 74  vtab.html">sqlit
90c0: 65 33 5f 76 74 61 62 3c 2f 61 3e 20 73 74 72 75  e3_vtab</a> stru
90d0: 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74 20 62  cture must not b
90e0: 65 20 0a 61 6c 6c 6f 63 61 74 65 64 2e 20 41 6e  e .allocated. An
90f0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6d   error message m
9100: 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65  ay optionally be
9110: 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 7a   returned in *pz
9120: 45 72 72 20 69 66 20 0a 75 6e 73 75 63 63 65 73  Err if .unsucces
9130: 73 66 75 6c 2e 20 0a 53 70 61 63 65 20 74 6f 20  sful. .Space to 
9140: 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
9150: 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 6d 75  essage string mu
9160: 73 74 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20  st be allocated 
9170: 75 73 69 6e 67 0a 61 6e 20 53 51 4c 69 74 65 20  using.an SQLite 
9180: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
9190: 6e 20 66 75 6e 63 74 69 6f 6e 20 6c 69 6b 65 20  n function like 
91a0: 0a 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f  .<a href="c3ref/
91b0: 66 72 65 65 2e 68 74 6d 6c 22 3e 73 71 6c 69 74  free.html">sqlit
91c0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 3c 2f 61 3e 20  e3_malloc()</a> 
91d0: 6f 72 20 3c 61 20 68 72 65 66 3d 22 63 33 72 65  or <a href="c3re
91e0: 66 2f 6d 70 72 69 6e 74 66 2e 68 74 6d 6c 22 3e  f/mprintf.html">
91f0: 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
9200: 29 3c 2f 61 3e 20 61 73 20 74 68 65 20 53 51 4c  )</a> as the SQL
9210: 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 0a 61 74  ite core will.at
9220: 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68  tempt to free th
9230: 65 20 73 70 61 63 65 20 75 73 69 6e 67 20 3c 61  e space using <a
9240: 20 68 72 65 66 3d 22 63 33 72 65 66 2f 66 72 65   href="c3ref/fre
9250: 65 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f  e.html">sqlite3_
9260: 66 72 65 65 28 29 3c 2f 61 3e 20 61 66 74 65 72  free()</a> after
9270: 20 74 68 65 20 65 72 72 6f 72 20 68 61 73 0a 62   the error has.b
9280: 65 65 6e 20 72 65 70 6f 72 74 65 64 20 75 70 20  een reported up 
9290: 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
92a0: 6f 6e 2e 0a 0a 3c 2f 70 3e 3c 70 3e 54 68 65 20  on...</p><p>The 
92b0: 78 43 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 20  xConnect method 
92c0: 69 73 20 72 65 71 75 69 72 65 64 20 66 6f 72 20  is required for 
92d0: 65 76 65 72 79 20 76 69 72 74 75 61 6c 20 74 61  every virtual ta
92e0: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
92f0: 6f 6e 2c 20 0a 74 68 6f 75 67 68 20 74 68 65 20  on, .though the 
9300: 3c 61 20 68 72 65 66 3d 22 76 74 61 62 2e 68 74  <a href="vtab.ht
9310: 6d 6c 23 78 63 72 65 61 74 65 22 3e 78 43 72 65  ml#xcreate">xCre
9320: 61 74 65 3c 2f 61 3e 20 61 6e 64 20 78 43 6f 6e  ate</a> and xCon
9330: 6e 65 63 74 20 70 6f 69 6e 74 65 72 73 20 6f 66  nect pointers of
9340: 20 74 68 65 20 3c 61 20 68 72 65 66 3d 22 63 33   the <a href="c3
9350: 72 65 66 2f 6d 6f 64 75 6c 65 2e 68 74 6d 6c 22  ref/module.html"
9360: 3e 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3c  >sqlite3_module<
9370: 2f 61 3e 20 6f 62 6a 65 63 74 0a 6d 61 79 20 70  /a> object.may p
9380: 6f 69 6e 74 20 74 6f 20 74 68 65 20 73 61 6d 65  oint to the same
9390: 20 66 75 6e 63 74 69 6f 6e 20 69 66 20 74 68 65   function if the
93a0: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 64   virtual table d
93b0: 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a  oes not need to.
93c0: 69 6e 69 74 69 61 6c 69 7a 65 20 62 61 63 6b 69  initialize backi
93d0: 6e 67 20 73 74 6f 72 65 2e 0a 0a 3c 61 20 6e 61  ng store...<a na
93e0: 6d 65 3d 22 78 62 65 73 74 69 6e 64 65 78 22 3e  me="xbestindex">
93f0: 3c 2f 61 3e 0a 0a 3c 2f 70 3e 3c 68 32 20 69 64  </a>..</p><h2 id
9400: 3d 22 74 68 65 5f 78 62 65 73 74 69 6e 64 65 78  ="the_xbestindex
9410: 5f 6d 65 74 68 6f 64 22 3e 3c 73 70 61 6e 3e 32  _method"><span>2
9420: 2e 33 2e 20 3c 2f 73 70 61 6e 3e 54 68 65 20 78  .3. </span>The x
9430: 42 65 73 74 49 6e 64 65 78 20 4d 65 74 68 6f 64  BestIndex Method
9440: 3c 2f 68 32 3e 0a 0a 3c 70 3e 53 51 4c 69 74 65  </h2>..<p>SQLite
9450: 20 75 73 65 73 20 74 68 65 20 78 42 65 73 74 49   uses the xBestI
9460: 6e 64 65 78 20 6d 65 74 68 6f 64 20 6f 66 20 61  ndex method of a
9470: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
9480: 6f 64 75 6c 65 20 74 6f 20 64 65 74 65 72 6d 69  odule to determi
9490: 6e 65 0a 74 68 65 20 62 65 73 74 20 77 61 79 20  ne.the best way 
94a0: 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 76 69  to access the vi
94b0: 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 0a 54 68  rtual table. .Th
94c0: 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74  e xBestIndex met
94d0: 68 6f 64 20 68 61 73 20 61 20 70 72 6f 74 6f 74  hod has a protot
94e0: 79 70 65 20 6c 69 6b 65 20 74 68 69 73 3a 0a 0a  ype like this:..
94f0: 3c 2f 70 3e 3c 64 69 76 20 63 6c 61 73 73 3d 22  </p><div class="
9500: 63 6f 64 65 62 6c 6f 63 6b 22 3e 3c 70 72 65 3e  codeblock"><pre>
9510: 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78  int (*xBestIndex
9520: 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
9530: 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69  pVTab, sqlite3_i
9540: 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 3c 2f 70  ndex_info*);.</p
9550: 72 65 3e 3c 2f 64 69 76 3e 0a 0a 3c 70 3e 54 68  re></div>..<p>Th
9560: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 63 6f  e SQLite core co
9570: 6d 6d 75 6e 69 63 61 74 65 73 20 77 69 74 68 20  mmunicates with 
9580: 74 68 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d  the xBestIndex m
9590: 65 74 68 6f 64 20 62 79 20 66 69 6c 6c 69 6e 67  ethod by filling
95a0: 20 0a 69 6e 20 63 65 72 74 61 69 6e 20 66 69 65   .in certain fie
95b0: 6c 64 73 20 6f 66 20 74 68 65 20 3c 61 20 68 72  lds of the <a hr
95c0: 65 66 3d 22 63 33 72 65 66 2f 69 6e 64 65 78 5f  ef="c3ref/index_
95d0: 69 6e 66 6f 2e 68 74 6d 6c 22 3e 73 71 6c 69 74  info.html">sqlit
95e0: 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3c 2f 61  e3_index_info</a
95f0: 3e 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20  > structure and 
9600: 70 61 73 73 69 6e 67 20 61 20 0a 70 6f 69 6e 74  passing a .point
9610: 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 75 63  er to that struc
9620: 74 75 72 65 20 69 6e 74 6f 20 78 42 65 73 74 49  ture into xBestI
9630: 6e 64 65 78 20 61 73 20 74 68 65 20 73 65 63 6f  ndex as the seco
9640: 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 0a 54  nd parameter. .T
9650: 68 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65  he xBestIndex me
9660: 74 68 6f 64 20 66 69 6c 6c 73 20 6f 75 74 20 6f  thod fills out o
9670: 74 68 65 72 20 66 69 65 6c 64 73 20 6f 66 20 74  ther fields of t
9680: 68 69 73 20 73 74 72 75 63 74 75 72 65 20 77 68  his structure wh
9690: 69 63 68 0a 66 6f 72 6d 73 20 74 68 65 20 72 65  ich.forms the re
96a0: 70 6c 79 2e 20 54 68 65 20 3c 61 20 68 72 65 66  ply. The <a href
96b0: 3d 22 63 33 72 65 66 2f 69 6e 64 65 78 5f 69 6e  ="c3ref/index_in
96c0: 66 6f 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33  fo.html">sqlite3
96d0: 5f 69 6e 64 65 78 5f 69 6e 66 6f 3c 2f 61 3e 20  _index_info</a> 
96e0: 73 74 72 75 63 74 75 72 65 20 6c 6f 6f 6b 73 20  structure looks 
96f0: 6c 69 6b 65 20 74 68 69 73 3a 0a 0a 3c 2f 70 3e  like this:..</p>
9700: 3c 64 69 76 20 63 6c 61 73 73 3d 22 63 6f 64 65  <div class="code
9710: 62 6c 6f 63 6b 22 3e 3c 70 72 65 3e 73 74 72 75  block"><pre>stru
9720: 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
9730: 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70  _info {.  /* Inp
9740: 75 74 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 69  uts */.  const i
9750: 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20  nt nConstraint; 
9760: 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
9770: 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e   entries in aCon
9780: 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 63 6f 6e  straint */.  con
9790: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
97a0: 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69  3_index_constrai
97b0: 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43  nt {.     int iC
97c0: 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20  olumn;          
97d0: 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 63 6f      /* Column co
97e0: 6e 73 74 72 61 69 6e 65 64 2e 20 20 2d 31 20 66  nstrained.  -1 f
97f0: 6f 72 20 52 4f 57 49 44 20 2a 2f 0a 20 20 20 20  or ROWID */.    
9800: 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f   unsigned char o
9810: 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f  p;         /* Co
9820: 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f  nstraint operato
9830: 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e  r */.     unsign
9840: 65 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20  ed char usable; 
9850: 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74      /* True if t
9860: 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69  his constraint i
9870: 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20  s usable */.    
9880: 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74   int iTermOffset
9890: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73  ;          /* Us
98a0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20  ed internally - 
98b0: 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c  xBestIndex shoul
98c0: 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20  d ignore */.  } 
98d0: 2a 63 6f 6e 73 74 20 61 43 6f 6e 73 74 72 61 69  *const aConstrai
98e0: 6e 74 3b 20 20 20 20 20 20 2f 2a 20 54 61 62 6c  nt;      /* Tabl
98f0: 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73  e of WHERE claus
9900: 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f  e constraints */
9910: 0a 20 20 63 6f 6e 73 74 20 69 6e 74 20 6e 4f 72  .  const int nOr
9920: 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 2f 2a  derBy;        /*
9930: 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   Number of terms
9940: 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59   in the ORDER BY
9950: 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 63 6f 6e   clause */.  con
9960: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
9970: 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79 20  3_index_orderby 
9980: 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75  {.     int iColu
9990: 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  mn;             
99a0: 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65   /* Column numbe
99b0: 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e  r */.     unsign
99c0: 65 64 20 63 68 61 72 20 64 65 73 63 3b 20 20 20  ed char desc;   
99d0: 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72 20      /* True for 
99e0: 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f 72  DESC.  False for
99f0: 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 63 6f   ASC. */.  } *co
9a00: 6e 73 74 20 61 4f 72 64 65 72 42 79 3b 20 20 20  nst aOrderBy;   
9a10: 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52 44        /* The ORD
9a20: 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a  ER BY clause */.
9a30: 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f  .  /* Outputs */
9a40: 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  .  struct sqlite
9a50: 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69  3_index_constrai
9a60: 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69  nt_usage {.    i
9a70: 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20  nt argvIndex;   
9a80: 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30          /* if >0
9a90: 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  , constraint is 
9aa0: 70 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20  part of argv to 
9ab0: 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75  xFilter */.    u
9ac0: 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69  nsigned char omi
9ad0: 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f  t;      /* Do no
9ae0: 74 20 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f  t code a test fo
9af0: 72 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e  r this constrain
9b00: 74 20 2a 2f 0a 20 20 7d 20 2a 63 6f 6e 73 74 20  t */.  } *const 
9b10: 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
9b20: 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20  ;.  int idxNum; 
9b30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
9b40: 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f  * Number used to
9b50: 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e   identify the in
9b60: 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69  dex */.  char *i
9b70: 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20  dxStr;          
9b80: 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70      /* String, p
9b90: 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64  ossibly obtained
9ba0: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
9bb0: 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65  lloc */.  int ne
9bc0: 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20  edToFreeIdxStr; 
9bd0: 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78       /* Free idx
9be0: 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65  Str using sqlite
9bf0: 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65  3_free() if true
9c00: 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42   */.  int orderB
9c10: 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20  yConsumed;      
9c20: 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70   /* True if outp
9c30: 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72  ut is already or
9c40: 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c  dered */.  doubl
9c50: 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b  e estimatedCost;
9c60: 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74        /* Estimat
9c70: 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67  ed cost of using
9c80: 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 20   this index */. 
9c90: 20 3c 62 3e 2f 2a 20 46 69 65 6c 64 73 20 62 65   <b>/* Fields be
9ca0: 6c 6f 77 20 61 72 65 20 6f 6e 6c 79 20 61 76 61  low are only ava
9cb0: 69 6c 61 62 6c 65 20 69 6e 20 53 51 4c 69 74 65  ilable in SQLite
9cc0: 20 33 2e 38 2e 32 20 61 6e 64 20 6c 61 74 65 72   3.8.2 and later
9cd0: 20 2a 2f 3c 2f 62 3e 0a 20 20 73 71 6c 69 74 65   */</b>.  sqlite
9ce0: 33 5f 69 6e 74 36 34 20 65 73 74 69 6d 61 74 65  3_int64 estimate
9cf0: 64 52 6f 77 73 3b 20 20 20 20 2f 2a 20 45 73 74  dRows;    /* Est
9d00: 69 6d 61 74 65 64 20 6e 75 6d 62 65 72 20 6f 66  imated number of
9d10: 20 72 6f 77 73 20 72 65 74 75 72 6e 65 64 20 2a   rows returned *
9d20: 2f 0a 20 20 3c 62 3e 2f 2a 20 46 69 65 6c 64 73  /.  <b>/* Fields
9d30: 20 62 65 6c 6f 77 20 61 72 65 20 6f 6e 6c 79 20   below are only 
9d40: 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 53 51 4c  available in SQL
9d50: 69 74 65 20 33 2e 39 2e 30 20 61 6e 64 20 6c 61  ite 3.9.0 and la
9d60: 74 65 72 20 2a 2f 3c 2f 62 3e 0a 20 20 69 6e 74  ter */</b>.  int
9d70: 20 69 64 78 46 6c 61 67 73 3b 20 20 20 20 20 20   idxFlags;      
9d80: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 73 6b 20          /* Mask 
9d90: 6f 66 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  of SQLITE_INDEX_
9da0: 53 43 41 4e 5f 2a 20 66 6c 61 67 73 20 2a 2f 0a  SCAN_* flags */.
9db0: 20 20 3c 62 3e 2f 2a 20 46 69 65 6c 64 73 20 62    <b>/* Fields b
9dc0: 65 6c 6f 77 20 61 72 65 20 6f 6e 6c 79 20 61 76  elow are only av
9dd0: 61 69 6c 61 62 6c 65 20 69 6e 20 53 51 4c 69 74  ailable in SQLit
9de0: 65 20 33 2e 31 30 2e 30 20 61 6e 64 20 6c 61 74  e 3.10.0 and lat
9df0: 65 72 20 2a 2f 3c 2f 62 3e 0a 20 20 73 71 6c 69  er */</b>.  sqli
9e00: 74 65 33 5f 75 69 6e 74 36 34 20 63 6f 6c 55 73  te3_uint64 colUs
9e10: 65 64 3b 20 20 20 20 2f 2a 20 49 6e 70 75 74 3a  ed;    /* Input:
9e20: 20 4d 61 73 6b 20 6f 66 20 63 6f 6c 75 6d 6e 73   Mask of columns
9e30: 20 75 73 65 64 20 62 79 20 73 74 61 74 65 6d 65   used by stateme
9e40: 6e 74 20 2a 2f 0a 7d 3b 0a 3c 2f 70 72 65 3e 3c  nt */.};.</pre><
9e50: 2f 64 69 76 3e 0a 0a 3c 70 3e 4e 6f 74 65 20 74  /div>..<p>Note t
9e60: 68 65 20 77 61 72 6e 69 6e 67 73 20 6f 6e 20 74  he warnings on t
9e70: 68 65 20 22 65 73 74 69 6d 61 74 65 64 52 6f 77  he "estimatedRow
9e80: 73 22 2c 20 22 69 64 78 46 6c 61 67 73 22 2c 20  s", "idxFlags", 
9e90: 61 6e 64 20 63 6f 6c 55 73 65 64 20 66 69 65 6c  and colUsed fiel
9ea0: 64 73 2e 0a 54 68 65 73 65 20 66 69 65 6c 64 73  ds..These fields
9eb0: 20 77 65 72 65 20 61 64 64 65 64 20 77 69 74 68   were added with
9ec0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 73   SQLite versions
9ed0: 20 33 2e 38 2e 32 2c 20 33 2e 39 2e 30 2c 20 61   3.8.2, 3.9.0, a
9ee0: 6e 64 20 33 2e 31 30 2e 30 2c 20 72 65 73 70 65  nd 3.10.0, respe
9ef0: 63 74 69 76 65 6c 79 2e 20 0a 41 6e 79 20 65 78  ctively. .Any ex
9f00: 74 65 6e 73 69 6f 6e 20 74 68 61 74 20 72 65 61  tension that rea
9f10: 64 73 20 6f 72 20 77 72 69 74 65 73 20 74 68 65  ds or writes the
9f20: 73 65 20 66 69 65 6c 64 73 20 6d 75 73 74 20 66  se fields must f
9f30: 69 72 73 74 20 63 68 65 63 6b 20 74 68 61 74 20  irst check that 
9f40: 74 68 65 20 0a 76 65 72 73 69 6f 6e 20 6f 66 20  the .version of 
9f50: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
9f60: 72 79 20 69 6e 20 75 73 65 20 69 73 20 67 72 65  ry in use is gre
9f70: 61 74 65 72 20 74 68 61 6e 20 6f 72 20 65 71 75  ater than or equ
9f80: 61 6c 20 74 6f 20 61 70 70 72 6f 70 72 69 61 74  al to appropriat
9f90: 65 0a 76 65 72 73 69 6f 6e 20 2d 20 70 65 72 68  e.version - perh
9fa0: 61 70 73 20 63 6f 6d 70 61 72 69 6e 67 20 74 68  aps comparing th
9fb0: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
9fc0: 20 66 72 6f 6d 20 3c 61 20 68 72 65 66 3d 22 63   from <a href="c
9fd0: 33 72 65 66 2f 6c 69 62 76 65 72 73 69 6f 6e 2e  3ref/libversion.
9fe0: 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 6c 69  html">sqlite3_li
9ff0: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
a000: 29 3c 2f 61 3e 0a 61 67 61 69 6e 73 74 20 63 6f  )</a>.against co
a010: 6e 73 74 61 6e 74 73 20 33 30 30 38 30 30 32 2c  nstants 3008002,
a020: 20 33 30 30 39 30 30 30 2c 20 61 6e 64 2f 6f 72   3009000, and/or
a030: 20 33 30 31 30 30 30 30 2e 20 54 68 65 20 72 65   3010000. The re
a040: 73 75 6c 74 20 6f 66 20 61 74 74 65 6d 70 74 69  sult of attempti
a050: 6e 67 20 0a 74 6f 20 61 63 63 65 73 73 20 74 68  ng .to access th
a060: 65 73 65 20 66 69 65 6c 64 73 20 69 6e 20 61 6e  ese fields in an
a070: 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
a080: 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 63 72  nfo structure cr
a090: 65 61 74 65 64 20 62 79 20 61 6e 20 0a 6f 6c 64  eated by an .old
a0a0: 65 72 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51  er version of SQ
a0b0: 4c 69 74 65 20 61 72 65 20 75 6e 64 65 66 69 6e  Lite are undefin
a0c0: 65 64 2e 0a 0a 3c 2f 70 3e 3c 70 3e 49 6e 20 61  ed...</p><p>In a
a0d0: 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 20 61  ddition, there a
a0e0: 72 65 20 73 6f 6d 65 20 64 65 66 69 6e 65 64 20  re some defined 
a0f0: 63 6f 6e 73 74 61 6e 74 73 3a 0a 0a 3c 2f 70 3e  constants:..</p>
a100: 3c 64 69 76 20 63 6c 61 73 73 3d 22 63 6f 64 65  <div class="code
a110: 62 6c 6f 63 6b 22 3e 3c 70 72 65 3e 23 64 65 66  block"><pre>#def
a120: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
a130: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20  _CONSTRAINT_EQ  
a140: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
a150: 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
a160: 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20 20  NSTRAINT_GT     
a170: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
a180: 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
a190: 52 41 49 4e 54 5f 4c 45 20 20 20 20 20 20 20 20  RAINT_LE        
a1a0: 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
a1b0: 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
a1c0: 4e 54 5f 4c 54 20 20 20 20 20 20 20 20 31 36 0a  NT_LT        16.
a1d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
a1e0: 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
a1f0: 47 45 20 20 20 20 20 20 20 20 33 32 0a 23 64 65  GE        32.#de
a200: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
a210: 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54  X_CONSTRAINT_MAT
a220: 43 48 20 20 20 20 20 36 34 0a 23 64 65 66 69 6e  CH     64.#defin
a230: 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
a240: 4f 4e 53 54 52 41 49 4e 54 5f 4c 49 4b 45 20 20  ONSTRAINT_LIKE  
a250: 20 20 20 20 36 35 20 20 2f 2a 20 33 2e 31 30 2e      65  /* 3.10.
a260: 30 20 61 6e 64 20 6c 61 74 65 72 20 2a 2f 0a 23  0 and later */.#
a270: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
a280: 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47  DEX_CONSTRAINT_G
a290: 4c 4f 42 20 20 20 20 20 20 36 36 20 20 2f 2a 20  LOB      66  /* 
a2a0: 33 2e 31 30 2e 30 20 61 6e 64 20 6c 61 74 65 72  3.10.0 and later
a2b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
a2c0: 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
a2d0: 49 4e 54 5f 52 45 47 45 58 50 20 20 20 20 36 37  INT_REGEXP    67
a2e0: 20 20 2f 2a 20 33 2e 31 30 2e 30 20 61 6e 64 20    /* 3.10.0 and 
a2f0: 6c 61 74 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  later */.#define
a300: 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
a310: 4e 53 54 52 41 49 4e 54 5f 4e 45 20 20 20 20 20  NSTRAINT_NE     
a320: 20 20 20 36 38 20 20 2f 2a 20 33 2e 32 31 2e 30     68  /* 3.21.0
a330: 20 61 6e 64 20 6c 61 74 65 72 20 2a 2f 0a 23 64   and later */.#d
a340: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
a350: 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 49 53  EX_CONSTRAINT_IS
a360: 4e 4f 54 20 20 20 20 20 36 39 20 20 2f 2a 20 33  NOT     69  /* 3
a370: 2e 32 31 2e 30 20 61 6e 64 20 6c 61 74 65 72 20  .21.0 and later 
a380: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a390: 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
a3a0: 4e 54 5f 49 53 4e 4f 54 4e 55 4c 4c 20 37 30 20  NT_ISNOTNULL 70 
a3b0: 20 2f 2a 20 33 2e 32 31 2e 30 20 61 6e 64 20 6c   /* 3.21.0 and l
a3c0: 61 74 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ater */.#define 
a3d0: 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
a3e0: 53 54 52 41 49 4e 54 5f 49 53 4e 55 4c 4c 20 20  STRAINT_ISNULL  
a3f0: 20 20 37 31 20 20 2f 2a 20 33 2e 32 31 2e 30 20    71  /* 3.21.0 
a400: 61 6e 64 20 6c 61 74 65 72 20 2a 2f 0a 23 64 65  and later */.#de
a410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
a420: 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 49 53 20  X_CONSTRAINT_IS 
a430: 20 20 20 20 20 20 20 37 32 20 20 2f 2a 20 33 2e         72  /* 3.
a440: 32 31 2e 30 20 61 6e 64 20 6c 61 74 65 72 20 2a  21.0 and later *
a450: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
a460: 5f 49 4e 44 45 58 5f 53 43 41 4e 5f 55 4e 49 51  _INDEX_SCAN_UNIQ
a470: 55 45 20 20 20 20 20 20 20 20 20 20 20 31 20 20  UE           1  
a480: 2f 2a 20 53 63 61 6e 20 76 69 73 69 74 73 20 61  /* Scan visits a
a490: 74 20 6d 6f 73 74 20 31 20 72 6f 77 20 2a 2f 0a  t most 1 row */.
a4a0: 3c 2f 70 72 65 3e 3c 2f 64 69 76 3e 0a 0a 3c 70  </pre></div>..<p
a4b0: 3e 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65  >The SQLite core
a4c0: 20 63 61 6c 6c 73 20 74 68 65 20 78 42 65 73 74   calls the xBest
a4d0: 49 6e 64 65 78 20 6d 65 74 68 6f 64 20 77 68 65  Index method whe
a4e0: 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 69 6e  n it is compilin
a4f0: 67 20 61 20 71 75 65 72 79 0a 74 68 61 74 20 69  g a query.that i
a500: 6e 76 6f 6c 76 65 73 20 61 20 76 69 72 74 75 61  nvolves a virtua
a510: 6c 20 74 61 62 6c 65 2e 20 49 6e 20 6f 74 68 65  l table. In othe
a520: 72 20 77 6f 72 64 73 2c 20 53 51 4c 69 74 65 20  r words, SQLite 
a530: 63 61 6c 6c 73 20 74 68 69 73 20 6d 65 74 68 6f  calls this metho
a540: 64 20 0a 77 68 65 6e 20 69 74 20 69 73 20 72 75  d .when it is ru
a550: 6e 6e 69 6e 67 20 3c 61 20 68 72 65 66 3d 22 63  nning <a href="c
a560: 33 72 65 66 2f 70 72 65 70 61 72 65 2e 68 74 6d  3ref/prepare.htm
a570: 6c 22 3e 73 71 6c 69 74 65 33 5f 70 72 65 70 61  l">sqlite3_prepa
a580: 72 65 28 29 3c 2f 61 3e 20 6f 72 20 74 68 65 20  re()</a> or the 
a590: 65 71 75 69 76 61 6c 65 6e 74 2e 20 0a 42 79 20  equivalent. .By 
a5a0: 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 6d 65 74  calling this met
a5b0: 68 6f 64 2c 20 74 68 65 20 0a 53 51 4c 69 74 65  hod, the .SQLite
a5c0: 20 63 6f 72 65 20 69 73 20 73 61 79 69 6e 67 20   core is saying 
a5d0: 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  to the virtual t
a5e0: 61 62 6c 65 20 74 68 61 74 20 69 74 20 6e 65 65  able that it nee
a5f0: 64 73 20 74 6f 20 61 63 63 65 73 73 20 0a 73 6f  ds to access .so
a600: 6d 65 20 73 75 62 73 65 74 20 6f 66 20 74 68 65  me subset of the
a610: 20 72 6f 77 73 20 69 6e 20 74 68 65 20 76 69 72   rows in the vir
a620: 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69  tual table and i
a630: 74 20 77 61 6e 74 73 20 74 6f 20 6b 6e 6f 77 20  t wants to know 
a640: 74 68 65 0a 6d 6f 73 74 20 65 66 66 69 63 69 65  the.most efficie
a650: 6e 74 20 77 61 79 20 74 6f 20 64 6f 20 74 68 61  nt way to do tha
a660: 74 20 61 63 63 65 73 73 2e 20 54 68 65 20 78 42  t access. The xB
a670: 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20  estIndex method 
a680: 72 65 70 6c 69 65 73 20 0a 77 69 74 68 20 69 6e  replies .with in
a690: 66 6f 72 6d 61 74 69 6f 6e 20 74 68 61 74 20 74  formation that t
a6a0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 63  he SQLite core c
a6b0: 61 6e 20 74 68 65 6e 20 75 73 65 20 74 6f 20 63  an then use to c
a6c0: 6f 6e 64 75 63 74 20 61 6e 20 0a 65 66 66 69 63  onduct an .effic
a6d0: 69 65 6e 74 20 73 65 61 72 63 68 20 6f 66 20 74  ient search of t
a6e0: 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
a6f0: 2e 0a 0a 3c 2f 70 3e 3c 70 3e 57 68 69 6c 65 20  ...</p><p>While 
a700: 63 6f 6d 70 69 6c 69 6e 67 20 61 20 73 69 6e 67  compiling a sing
a710: 6c 65 20 53 51 4c 20 71 75 65 72 79 2c 20 74 68  le SQL query, th
a720: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6d 69  e SQLite core mi
a730: 67 68 74 20 63 61 6c 6c 20 0a 78 42 65 73 74 49  ght call .xBestI
a740: 6e 64 65 78 20 6d 75 6c 74 69 70 6c 65 20 74 69  ndex multiple ti
a750: 6d 65 73 20 77 69 74 68 20 64 69 66 66 65 72 65  mes with differe
a760: 6e 74 20 73 65 74 74 69 6e 67 73 20 69 6e 20 3c  nt settings in <
a770: 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f 69 6e  a href="c3ref/in
a780: 64 65 78 5f 69 6e 66 6f 2e 68 74 6d 6c 22 3e 73  dex_info.html">s
a790: 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
a7a0: 6f 3c 2f 61 3e 2e 0a 54 68 65 20 53 51 4c 69 74  o</a>..The SQLit
a7b0: 65 20 63 6f 72 65 20 77 69 6c 6c 20 74 68 65 6e  e core will then
a7c0: 20 73 65 6c 65 63 74 20 74 68 65 20 63 6f 6d 62   select the comb
a7d0: 69 6e 61 74 69 6f 6e 20 74 68 61 74 20 61 70 70  ination that app
a7e0: 65 61 72 73 20 74 6f 20 0a 67 69 76 65 20 74 68  ears to .give th
a7f0: 65 20 62 65 73 74 20 70 65 72 66 6f 72 6d 61 6e  e best performan
a800: 63 65 2e 0a 0a 3c 2f 70 3e 3c 70 3e 42 65 66 6f  ce...</p><p>Befo
a810: 72 65 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20  re calling this 
a820: 6d 65 74 68 6f 64 2c 20 74 68 65 20 53 51 4c 69  method, the SQLi
a830: 74 65 20 63 6f 72 65 20 69 6e 69 74 69 61 6c 69  te core initiali
a840: 7a 65 73 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  zes an instance 
a850: 0a 6f 66 20 74 68 65 20 3c 61 20 68 72 65 66 3d  .of the <a href=
a860: 22 63 33 72 65 66 2f 69 6e 64 65 78 5f 69 6e 66  "c3ref/index_inf
a870: 6f 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f  o.html">sqlite3_
a880: 69 6e 64 65 78 5f 69 6e 66 6f 3c 2f 61 3e 20 73  index_info</a> s
a890: 74 72 75 63 74 75 72 65 20 77 69 74 68 20 69 6e  tructure with in
a8a0: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
a8b0: 74 68 65 0a 71 75 65 72 79 20 74 68 61 74 20 69  the.query that i
a8c0: 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 74  t is currently t
a8d0: 72 79 69 6e 67 20 74 6f 20 70 72 6f 63 65 73 73  rying to process
a8e0: 2e 20 54 68 69 73 20 69 6e 66 6f 72 6d 61 74 69  . This informati
a8f0: 6f 6e 20 0a 64 65 72 69 76 65 73 20 6d 61 69 6e  on .derives main
a900: 6c 79 20 66 72 6f 6d 20 74 68 65 20 57 48 45 52  ly from the WHER
a910: 45 20 63 6c 61 75 73 65 20 61 6e 64 20 4f 52 44  E clause and ORD
a920: 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42  ER BY or GROUP B
a930: 59 20 63 6c 61 75 73 65 73 20 0a 6f 66 20 74 68  Y clauses .of th
a940: 65 20 71 75 65 72 79 2c 20 62 75 74 20 61 6c 73  e query, but als
a950: 6f 20 66 72 6f 6d 20 61 6e 79 20 4f 4e 20 6f 72  o from any ON or
a960: 20 55 53 49 4e 47 20 63 6c 61 75 73 65 73 20 69   USING clauses i
a970: 66 20 74 68 65 20 71 75 65 72 79 20 69 73 20 61  f the query is a
a980: 20 0a 6a 6f 69 6e 2e 20 54 68 65 20 69 6e 66 6f   .join. The info
a990: 72 6d 61 74 69 6f 6e 20 74 68 61 74 20 74 68 65  rmation that the
a9a0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 70 72 6f   SQLite core pro
a9b0: 76 69 64 65 73 20 74 6f 20 74 68 65 20 78 42 65  vides to the xBe
a9c0: 73 74 49 6e 64 65 78 20 0a 6d 65 74 68 6f 64 20  stIndex .method 
a9d0: 69 73 20 68 65 6c 64 20 69 6e 20 74 68 65 20 70  is held in the p
a9e0: 61 72 74 20 6f 66 20 74 68 65 20 73 74 72 75 63  art of the struc
a9f0: 74 75 72 65 20 74 68 61 74 20 69 73 20 6d 61 72  ture that is mar
aa00: 6b 65 64 20 61 73 20 22 49 6e 70 75 74 73 22 2e  ked as "Inputs".
aa10: 20 0a 54 68 65 20 22 4f 75 74 70 75 74 73 22 20   .The "Outputs" 
aa20: 73 65 63 74 69 6f 6e 20 69 73 20 69 6e 69 74 69  section is initi
aa30: 61 6c 69 7a 65 64 20 74 6f 20 7a 65 72 6f 2e 0a  alized to zero..
aa40: 0a 3c 2f 70 3e 3c 70 3e 54 68 65 20 69 6e 66 6f  .</p><p>The info
aa50: 72 6d 61 74 69 6f 6e 20 69 6e 20 74 68 65 20 3c  rmation in the <
aa60: 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f 69 6e  a href="c3ref/in
aa70: 64 65 78 5f 69 6e 66 6f 2e 68 74 6d 6c 22 3e 73  dex_info.html">s
aa80: 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
aa90: 6f 3c 2f 61 3e 20 73 74 72 75 63 74 75 72 65 20  o</a> structure 
aaa0: 69 73 20 65 70 68 65 6d 65 72 61 6c 0a 61 6e 64  is ephemeral.and
aab0: 20 6d 61 79 20 62 65 20 6f 76 65 72 77 72 69 74   may be overwrit
aac0: 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ten or deallocat
aad0: 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
aae0: 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74  e xBestIndex met
aaf0: 68 6f 64 0a 72 65 74 75 72 6e 73 2e 20 20 49 66  hod.returns.  If
ab00: 20 74 68 65 20 78 42 65 73 74 49 6e 64 65 78 20   the xBestIndex 
ab10: 6d 65 74 68 6f 64 20 6e 65 65 64 73 20 74 6f 20  method needs to 
ab20: 72 65 6d 65 6d 62 65 72 20 61 6e 79 20 70 61 72  remember any par
ab30: 74 20 6f 66 20 74 68 65 0a 3c 61 20 68 72 65 66  t of the.<a href
ab40: 3d 22 63 33 72 65 66 2f 69 6e 64 65 78 5f 69 6e  ="c3ref/index_in
ab50: 66 6f 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33  fo.html">sqlite3
ab60: 5f 69 6e 64 65 78 5f 69 6e 66 6f 3c 2f 61 3e 20  _index_info</a> 
ab70: 73 74 72 75 63 74 75 72 65 2c 20 69 74 20 73 68  structure, it sh
ab80: 6f 75 6c 64 20 6d 61 6b 65 20 61 20 63 6f 70 79  ould make a copy
ab90: 2e 20 20 43 61 72 65 20 6d 75 73 74 20 62 65 0a  .  Care must be.
aba0: 74 61 6b 65 20 74 6f 20 73 74 6f 72 65 20 74 68  take to store th
abb0: 65 20 63 6f 70 79 20 69 6e 20 61 20 70 6c 61 63  e copy in a plac
abc0: 65 20 77 68 65 72 65 20 69 74 20 77 69 6c 6c 20  e where it will 
abd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2c 20  be deallocated, 
abe0: 73 75 63 68 0a 61 73 20 69 6e 20 74 68 65 20 69  such.as in the i
abf0: 64 78 53 74 72 20 66 69 65 6c 64 20 77 69 74 68  dxStr field with
ac00: 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74   needToFreeIdxSt
ac10: 72 20 73 65 74 20 74 6f 20 31 2e 0a 0a 3c 2f 70  r set to 1...</p
ac20: 3e 3c 70 3e 4e 6f 74 65 20 74 68 61 74 20 78 42  ><p>Note that xB
ac30: 65 73 74 49 6e 64 65 78 20 77 69 6c 6c 20 61 6c  estIndex will al
ac40: 77 61 79 73 20 62 65 20 63 61 6c 6c 65 64 20 62  ways be called b
ac50: 65 66 6f 72 65 20 3c 61 20 68 72 65 66 3d 22 76  efore <a href="v
ac60: 74 61 62 2e 68 74 6d 6c 23 78 66 69 6c 74 65 72  tab.html#xfilter
ac70: 22 3e 78 46 69 6c 74 65 72 3c 2f 61 3e 2c 20 73  ">xFilter</a>, s
ac80: 69 6e 63 65 0a 74 68 65 20 69 64 78 4e 75 6d 20  ince.the idxNum 
ac90: 61 6e 64 20 69 64 78 53 74 72 20 6f 75 74 70 75  and idxStr outpu
aca0: 74 73 20 66 72 6f 6d 20 78 42 65 73 74 49 6e 64  ts from xBestInd
acb0: 65 78 20 61 72 65 20 72 65 71 75 69 72 65 64 20  ex are required 
acc0: 69 6e 70 75 74 73 20 74 6f 0a 78 46 69 6c 74 65  inputs to.xFilte
acd0: 72 2e 20 20 48 6f 77 65 76 65 72 2c 20 74 68 65  r.  However, the
ace0: 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74  re is no guarant
acf0: 65 65 20 74 68 61 74 20 78 46 69 6c 74 65 72 20  ee that xFilter 
ad00: 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 0a 66  will be called.f
ad10: 6f 6c 6c 6f 77 69 6e 67 20 61 20 73 75 63 63 65  ollowing a succe
ad20: 73 73 66 75 6c 20 78 42 65 73 74 49 6e 64 65 78  ssful xBestIndex
ad30: 2e 20 20 0a 0a 3c 2f 70 3e 3c 70 3e 54 68 65 20  .  ..</p><p>The 
ad40: 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f  xBestIndex metho
ad50: 64 20 69 73 20 72 65 71 75 69 72 65 64 20 66 6f  d is required fo
ad60: 72 20 65 76 65 72 79 20 76 69 72 74 75 61 6c 20  r every virtual 
ad70: 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
ad80: 74 69 6f 6e 2e 0a 0a 3c 2f 70 3e 3c 68 33 20 69  tion...</p><h3 i
ad90: 64 3d 22 69 6e 70 75 74 73 22 3e 3c 73 70 61 6e  d="inputs"><span
ada0: 3e 32 2e 33 2e 31 2e 20 3c 2f 73 70 61 6e 3e 49  >2.3.1. </span>I
adb0: 6e 70 75 74 73 3c 2f 68 33 3e 0a 0a 3c 70 3e 54  nputs</h3>..<p>T
adc0: 68 65 20 6d 61 69 6e 20 74 68 69 6e 67 20 74 68  he main thing th
add0: 61 74 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  at the SQLite co
ade0: 72 65 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20  re is trying to 
adf0: 63 6f 6d 6d 75 6e 69 63 61 74 65 20 74 6f 20 0a  communicate to .
ae00: 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
ae10: 65 20 69 73 20 74 68 65 20 63 6f 6e 73 74 72 61  e is the constra
ae20: 69 6e 74 73 20 74 68 61 74 20 61 72 65 20 61 76  ints that are av
ae30: 61 69 6c 61 62 6c 65 20 74 6f 20 6c 69 6d 69 74  ailable to limit
ae40: 20 0a 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   .the number of 
ae50: 72 6f 77 73 20 74 68 61 74 20 6e 65 65 64 20 74  rows that need t
ae60: 6f 20 62 65 20 73 65 61 72 63 68 65 64 2e 20 54  o be searched. T
ae70: 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  he aConstraint[]
ae80: 20 61 72 72 61 79 20 0a 63 6f 6e 74 61 69 6e 73   array .contains
ae90: 20 6f 6e 65 20 65 6e 74 72 79 20 66 6f 72 20 65   one entry for e
aea0: 61 63 68 20 63 6f 6e 73 74 72 61 69 6e 74 2e 20  ach constraint. 
aeb0: 54 68 65 72 65 20 77 69 6c 6c 20 62 65 20 65 78  There will be ex
aec0: 61 63 74 6c 79 20 0a 6e 43 6f 6e 73 74 72 61 69  actly .nConstrai
aed0: 6e 74 20 65 6e 74 72 69 65 73 20 69 6e 20 74 68  nt entries in th
aee0: 61 74 20 61 72 72 61 79 2e 0a 0a 3c 2f 70 3e 3c  at array...</p><
aef0: 70 3e 45 61 63 68 20 63 6f 6e 73 74 72 61 69 6e  p>Each constrain
af00: 74 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e  t will correspon
af10: 64 20 74 6f 20 61 20 74 65 72 6d 20 69 6e 20 74  d to a term in t
af20: 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a  he WHERE clause.
af30: 6f 72 20 69 6e 20 61 20 55 53 49 4e 47 20 6f 72  or in a USING or
af40: 20 4f 4e 20 63 6c 61 75 73 65 20 74 68 61 74 20   ON clause that 
af50: 69 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 0a 0a  is of the form..
af60: 3c 2f 70 3e 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  </p><blockquote>
af70: 0a 20 20 20 20 20 63 6f 6c 75 6d 6e 20 20 4f 50  .     column  OP
af80: 20 20 45 58 50 52 0a 3c 2f 62 6c 6f 63 6b 71 75    EXPR.</blockqu
af90: 6f 74 65 3e 0a 0a 3c 70 3e 57 68 65 72 65 20 22  ote>..<p>Where "
afa0: 63 6f 6c 75 6d 6e 22 20 69 73 20 61 20 63 6f 6c  column" is a col
afb0: 75 6d 6e 20 69 6e 20 74 68 65 20 76 69 72 74 75  umn in the virtu
afc0: 61 6c 20 74 61 62 6c 65 2c 20 4f 50 20 69 73 20  al table, OP is 
afd0: 61 6e 20 6f 70 65 72 61 74 6f 72 20 0a 6c 69 6b  an operator .lik
afe0: 65 20 22 3d 22 20 6f 72 20 22 26 6c 74 3b 22 2c  e "=" or "&lt;",
aff0: 20 61 6e 64 20 45 58 50 52 20 69 73 20 61 6e 20   and EXPR is an 
b000: 61 72 62 69 74 72 61 72 79 20 65 78 70 72 65 73  arbitrary expres
b010: 73 69 6f 6e 2e 20 53 6f 2c 20 66 6f 72 20 65 78  sion. So, for ex
b020: 61 6d 70 6c 65 2c 0a 69 66 20 74 68 65 20 57 48  ample,.if the WH
b030: 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 74 61  ERE clause conta
b040: 69 6e 65 64 20 61 20 74 65 72 6d 20 6c 69 6b 65  ined a term like
b050: 20 74 68 69 73 3a 0a 0a 3c 2f 70 3e 3c 64 69 76   this:..</p><div
b060: 20 63 6c 61 73 73 3d 22 63 6f 64 65 62 6c 6f 63   class="codebloc
b070: 6b 22 3e 3c 70 72 65 3e 61 20 3d 20 35 0a 3c 2f  k"><pre>a = 5.</
b080: 70 72 65 3e 3c 2f 64 69 76 3e 0a 0a 3c 70 3e 54  pre></div>..<p>T
b090: 68 65 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 63  hen one of the c
b0a0: 6f 6e 73 74 72 61 69 6e 74 73 20 77 6f 75 6c 64  onstraints would
b0b0: 20 62 65 20 6f 6e 20 74 68 65 20 22 61 22 20 63   be on the "a" c
b0c0: 6f 6c 75 6d 6e 20 77 69 74 68 20 0a 6f 70 65 72  olumn with .oper
b0d0: 61 74 6f 72 20 22 3d 22 20 61 6e 64 20 61 6e 20  ator "=" and an 
b0e0: 65 78 70 72 65 73 73 69 6f 6e 20 6f 66 20 22 35  expression of "5
b0f0: 22 2e 20 43 6f 6e 73 74 72 61 69 6e 74 73 20 6e  ". Constraints n
b100: 65 65 64 20 6e 6f 74 20 68 61 76 65 20 61 0a 6c  eed not have a.l
b110: 69 74 65 72 61 6c 20 72 65 70 72 65 73 65 6e 74  iteral represent
b120: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 57 48 45  ation of the WHE
b130: 52 45 20 63 6c 61 75 73 65 2e 20 54 68 65 20 71  RE clause. The q
b140: 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 20 6d  uery optimizer m
b150: 69 67 68 74 0a 6d 61 6b 65 20 74 72 61 6e 73 66  ight.make transf
b160: 6f 72 6d 61 74 69 6f 6e 73 20 74 6f 20 74 68 65  ormations to the
b170: 20 0a 57 48 45 52 45 20 63 6c 61 75 73 65 20 69   .WHERE clause i
b180: 6e 20 6f 72 64 65 72 20 74 6f 20 65 78 74 72 61  n order to extra
b190: 63 74 20 61 73 20 6d 61 6e 79 20 63 6f 6e 73 74  ct as many const
b1a0: 72 61 69 6e 74 73 20 0a 61 73 20 69 74 20 63 61  raints .as it ca
b1b0: 6e 2e 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  n. So, for examp
b1c0: 6c 65 2c 20 69 66 20 74 68 65 20 57 48 45 52 45  le, if the WHERE
b1d0: 20 63 6c 61 75 73 65 20 63 6f 6e 74 61 69 6e 65   clause containe
b1e0: 64 20 73 6f 6d 65 74 68 69 6e 67 20 0a 6c 69 6b  d something .lik
b1f0: 65 20 74 68 69 73 3a 0a 0a 3c 2f 70 3e 3c 64 69  e this:..</p><di
b200: 76 20 63 6c 61 73 73 3d 22 63 6f 64 65 62 6c 6f  v class="codeblo
b210: 63 6b 22 3e 3c 70 72 65 3e 78 20 42 45 54 57 45  ck"><pre>x BETWE
b220: 45 4e 20 31 30 20 41 4e 44 20 31 30 30 20 41 4e  EN 10 AND 100 AN
b230: 44 20 39 39 39 26 67 74 3b 79 0a 3c 2f 70 72 65  D 999&gt;y.</pre
b240: 3e 3c 2f 64 69 76 3e 0a 0a 3c 70 3e 54 68 65 20  ></div>..<p>The 
b250: 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 20  query optimizer 
b260: 6d 69 67 68 74 20 74 72 61 6e 73 6c 61 74 65 20  might translate 
b270: 74 68 69 73 20 69 6e 74 6f 20 74 68 72 65 65 20  this into three 
b280: 73 65 70 61 72 61 74 65 20 63 6f 6e 73 74 72 61  separate constra
b290: 69 6e 74 73 3a 0a 0a 3c 2f 70 3e 3c 64 69 76 20  ints:..</p><div 
b2a0: 63 6c 61 73 73 3d 22 63 6f 64 65 62 6c 6f 63 6b  class="codeblock
b2b0: 22 3e 3c 70 72 65 3e 78 20 26 67 74 3b 3d 20 31  "><pre>x &gt;= 1
b2c0: 30 0a 78 20 26 6c 74 3b 3d 20 31 30 30 0a 79 20  0.x &lt;= 100.y 
b2d0: 26 6c 74 3b 20 39 39 39 0a 3c 2f 70 72 65 3e 3c  &lt; 999.</pre><
b2e0: 2f 64 69 76 3e 0a 0a 3c 70 3e 46 6f 72 20 65 61  /div>..<p>For ea
b2f0: 63 68 20 63 6f 6e 73 74 72 61 69 6e 74 2c 20 74  ch constraint, t
b300: 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  he aConstraint[]
b310: 2e 69 43 6f 6c 75 6d 6e 20 66 69 65 6c 64 20 69  .iColumn field i
b320: 6e 64 69 63 61 74 65 73 20 77 68 69 63 68 20 0a  ndicates which .
b330: 63 6f 6c 75 6d 6e 20 61 70 70 65 61 72 73 20 6f  column appears o
b340: 6e 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20  n the left-hand 
b350: 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f 6e 73  side of the cons
b360: 74 72 61 69 6e 74 2e 0a 54 68 65 20 66 69 72 73  traint..The firs
b370: 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
b380: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73  virtual table is
b390: 20 63 6f 6c 75 6d 6e 20 30 2e 20 0a 54 68 65 20   column 0. .The 
b3a0: 72 6f 77 69 64 20 6f 66 20 74 68 65 20 76 69 72  rowid of the vir
b3b0: 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20 63 6f  tual table is co
b3c0: 6c 75 6d 6e 20 2d 31 2e 20 0a 54 68 65 20 61 43  lumn -1. .The aC
b3d0: 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 66  onstraint[].op f
b3e0: 69 65 6c 64 20 69 6e 64 69 63 61 74 65 73 20 77  ield indicates w
b3f0: 68 69 63 68 20 6f 70 65 72 61 74 6f 72 20 69 73  hich operator is
b400: 20 75 73 65 64 2e 20 0a 54 68 65 20 53 51 4c 49   used. .The SQLI
b410: 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
b420: 49 4e 54 5f 2a 20 63 6f 6e 73 74 61 6e 74 73 20  INT_* constants 
b430: 6d 61 70 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  map integer cons
b440: 74 61 6e 74 73 20 0a 69 6e 74 6f 20 6f 70 65 72  tants .into oper
b450: 61 74 6f 72 20 76 61 6c 75 65 73 2e 0a 43 6f 6c  ator values..Col
b460: 75 6d 6e 73 20 6f 63 63 75 72 20 69 6e 20 74 68  umns occur in th
b470: 65 20 6f 72 64 65 72 20 74 68 65 79 20 77 65 72  e order they wer
b480: 65 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 65  e defined by the
b490: 20 63 61 6c 6c 20 74 6f 0a 3c 61 20 68 72 65 66   call to.<a href
b4a0: 3d 22 63 33 72 65 66 2f 64 65 63 6c 61 72 65 5f  ="c3ref/declare_
b4b0: 76 74 61 62 2e 68 74 6d 6c 22 3e 73 71 6c 69 74  vtab.html">sqlit
b4c0: 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28  e3_declare_vtab(
b4d0: 29 3c 2f 61 3e 20 69 6e 20 74 68 65 20 3c 61 20  )</a> in the <a 
b4e0: 68 72 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23  href="vtab.html#
b4f0: 78 63 72 65 61 74 65 22 3e 78 43 72 65 61 74 65  xcreate">xCreate
b500: 3c 2f 61 3e 20 6f 72 20 3c 61 20 68 72 65 66 3d  </a> or <a href=
b510: 22 76 74 61 62 2e 68 74 6d 6c 23 78 63 6f 6e 6e  "vtab.html#xconn
b520: 65 63 74 22 3e 78 43 6f 6e 6e 65 63 74 3c 2f 61  ect">xConnect</a
b530: 3e 20 6d 65 74 68 6f 64 2e 0a 48 69 64 64 65 6e  > method..Hidden
b540: 20 63 6f 6c 75 6d 6e 73 20 61 72 65 20 63 6f 75   columns are cou
b550: 6e 74 65 64 20 77 68 65 6e 20 64 65 74 65 72 6d  nted when determ
b560: 69 6e 69 6e 67 20 74 68 65 20 63 6f 6c 75 6d 6e  ining the column
b570: 20 69 6e 64 65 78 2e 0a 0a 3c 2f 70 3e 3c 70 3e   index...</p><p>
b580: 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  The aConstraint[
b590: 5d 20 61 72 72 61 79 20 63 6f 6e 74 61 69 6e 73  ] array contains
b5a0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
b5b0: 75 74 20 61 6c 6c 20 63 6f 6e 73 74 72 61 69 6e  ut all constrain
b5c0: 74 73 20 0a 74 68 61 74 20 61 70 70 6c 79 20 74  ts .that apply t
b5d0: 6f 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  o the virtual ta
b5e0: 62 6c 65 2e 20 42 75 74 20 73 6f 6d 65 20 6f 66  ble. But some of
b5f0: 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 73   the constraints
b600: 20 6d 69 67 68 74 0a 6e 6f 74 20 62 65 20 75 73   might.not be us
b610: 61 62 6c 65 20 62 65 63 61 75 73 65 20 6f 66 20  able because of 
b620: 74 68 65 20 77 61 79 20 74 61 62 6c 65 73 20 61  the way tables a
b630: 72 65 20 6f 72 64 65 72 65 64 20 69 6e 20 61 20  re ordered in a 
b640: 6a 6f 69 6e 2e 20 0a 54 68 65 20 78 42 65 73 74  join. .The xBest
b650: 49 6e 64 65 78 20 6d 65 74 68 6f 64 20 6d 75 73  Index method mus
b660: 74 20 74 68 65 72 65 66 6f 72 65 20 6f 6e 6c 79  t therefore only
b670: 20 63 6f 6e 73 69 64 65 72 20 63 6f 6e 73 74 72   consider constr
b680: 61 69 6e 74 73 20 0a 74 68 61 74 20 68 61 76 65  aints .that have
b690: 20 61 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b   an aConstraint[
b6a0: 5d 2e 75 73 61 62 6c 65 20 66 6c 61 67 20 77 68  ].usable flag wh
b6b0: 69 63 68 20 69 73 20 74 72 75 65 2e 0a 0a 3c 2f  ich is true...</
b6c0: 70 3e 3c 70 3e 49 6e 20 61 64 64 69 74 69 6f 6e  p><p>In addition
b6d0: 20 74 6f 20 57 48 45 52 45 20 63 6c 61 75 73 65   to WHERE clause
b6e0: 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 20 74 68   constraints, th
b6f0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6c  e SQLite core al
b700: 73 6f 20 0a 74 65 6c 6c 73 20 74 68 65 20 78 42  so .tells the xB
b710: 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64 20  estIndex method 
b720: 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20  about the ORDER 
b730: 42 59 20 63 6c 61 75 73 65 2e 20 0a 28 49 6e 20  BY clause. .(In 
b740: 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65  an aggregate que
b750: 72 79 2c 20 74 68 65 20 53 51 4c 69 74 65 20 63  ry, the SQLite c
b760: 6f 72 65 20 6d 69 67 68 74 20 70 75 74 20 69 6e  ore might put in
b770: 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
b780: 20 0a 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e   .information in
b790: 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 4f 52   place of the OR
b7a0: 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 69 6e  DER BY clause in
b7b0: 66 6f 72 6d 61 74 69 6f 6e 2c 20 62 75 74 20 74  formation, but t
b7c0: 68 69 73 20 66 61 63 74 0a 73 68 6f 75 6c 64 20  his fact.should 
b7d0: 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 64 69 66  not make any dif
b7e0: 66 65 72 65 6e 63 65 20 74 6f 20 74 68 65 20 78  ference to the x
b7f0: 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64  BestIndex method
b800: 2e 29 20 0a 49 66 20 61 6c 6c 20 74 65 72 6d 73  .) .If all terms
b810: 20 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42 59   of the ORDER BY
b820: 20 63 6c 61 75 73 65 20 61 72 65 20 63 6f 6c 75   clause are colu
b830: 6d 6e 73 20 69 6e 20 74 68 65 20 76 69 72 74 75  mns in the virtu
b840: 61 6c 20 74 61 62 6c 65 2c 20 0a 74 68 65 6e 20  al table, .then 
b850: 6e 4f 72 64 65 72 42 79 20 77 69 6c 6c 20 62 65  nOrderBy will be
b860: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
b870: 65 72 6d 73 20 69 6e 20 74 68 65 20 4f 52 44 45  erms in the ORDE
b880: 52 20 42 59 20 63 6c 61 75 73 65 20 0a 61 6e 64  R BY clause .and
b890: 20 74 68 65 20 61 4f 72 64 65 72 42 79 5b 5d 20   the aOrderBy[] 
b8a0: 61 72 72 61 79 20 77 69 6c 6c 20 69 64 65 6e 74  array will ident
b8b0: 69 66 79 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66  ify the column f
b8c0: 6f 72 20 65 61 63 68 20 74 65 72 6d 20 0a 69 6e  or each term .in
b8d0: 20 74 68 65 20 6f 72 64 65 72 20 62 79 20 63 6c   the order by cl
b8e0: 61 75 73 65 20 61 6e 64 20 77 68 65 74 68 65 72  ause and whether
b8f0: 20 6f 72 20 6e 6f 74 20 74 68 61 74 20 63 6f 6c   or not that col
b900: 75 6d 6e 20 69 73 20 41 53 43 20 6f 72 20 44 45  umn is ASC or DE
b910: 53 43 2e 0a 0a 3c 61 20 6e 61 6d 65 3d 22 63 6f  SC...<a name="co
b920: 6c 55 73 65 64 22 3e 3c 2f 61 3e 0a 0a 3c 2f 70  lUsed"></a>..</p
b930: 3e 3c 70 3e 49 6e 20 53 51 4c 69 74 65 20 3c 61  ><p>In SQLite <a
b940: 20 68 72 65 66 3d 22 72 65 6c 65 61 73 65 6c 6f   href="releaselo
b950: 67 2f 33 5f 31 30 5f 30 2e 68 74 6d 6c 22 3e 76  g/3_10_0.html">v
b960: 65 72 73 69 6f 6e 20 33 2e 31 30 2e 30 3c 2f 61  ersion 3.10.0</a
b970: 3e 20 28 32 30 31 36 2d 30 31 2d 30 36 29 20 61  > (2016-01-06) a
b980: 6e 64 20 6c 61 74 65 72 2c 20 0a 74 68 65 20 63  nd later, .the c
b990: 6f 6c 55 73 65 64 20 66 69 65 6c 64 20 69 73 20  olUsed field is 
b9a0: 61 76 61 69 6c 61 62 6c 65 0a 74 6f 20 69 6e 64  available.to ind
b9b0: 69 63 61 74 65 20 77 68 69 63 68 20 66 69 65 6c  icate which fiel
b9c0: 64 73 20 6f 66 20 74 68 65 20 76 69 72 74 75 61  ds of the virtua
b9d0: 6c 20 74 61 62 6c 65 20 61 72 65 20 61 63 74 75  l table are actu
b9e0: 61 6c 6c 79 20 75 73 65 64 20 62 79 20 74 68 65  ally used by the
b9f0: 0a 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67  .statement being
ba00: 20 70 72 65 70 61 72 65 64 2e 20 20 49 66 20 74   prepared.  If t
ba10: 68 65 20 6c 6f 77 65 73 74 20 62 69 74 20 6f 66  he lowest bit of
ba20: 20 63 6f 6c 55 73 65 64 20 69 73 20 73 65 74 2c   colUsed is set,
ba30: 20 74 68 61 74 0a 6d 65 61 6e 73 20 74 68 61 74   that.means that
ba40: 20 74 68 65 20 66 69 72 73 74 20 63 6f 6c 75 6d   the first colum
ba50: 6e 20 69 73 20 75 73 65 64 2e 20 20 54 68 65 20  n is used.  The 
ba60: 73 65 63 6f 6e 64 20 6c 6f 77 65 73 74 20 62 69  second lowest bi
ba70: 74 20 63 6f 72 72 65 73 70 6f 6e 64 73 0a 74 6f  t corresponds.to
ba80: 20 74 68 65 20 73 65 63 6f 6e 64 20 63 6f 6c 75   the second colu
ba90: 6d 6e 2e 20 20 41 6e 64 20 73 6f 20 66 6f 72 74  mn.  And so fort
baa0: 68 2e 20 20 49 66 20 74 68 65 20 6d 6f 73 74 20  h.  If the most 
bab0: 73 69 67 6e 69 66 69 63 61 6e 74 20 62 69 74 20  significant bit 
bac0: 6f 66 0a 63 6f 6c 55 73 65 64 20 69 73 20 73 65  of.colUsed is se
bad0: 74 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  t, that means th
bae0: 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  at one or more c
baf0: 6f 6c 75 6d 6e 73 20 6f 74 68 65 72 20 74 68 61  olumns other tha
bb00: 6e 20 74 68 65 20 0a 66 69 72 73 74 20 36 33 20  n the .first 63 
bb10: 63 6f 6c 75 6d 6e 73 20 61 72 65 20 75 73 65 64  columns are used
bb20: 2e 20 20 49 66 20 63 6f 6c 75 6d 6e 20 75 73 61  .  If column usa
bb30: 67 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ge information i
bb40: 73 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 0a  s needed by the.
bb50: 3c 61 20 68 72 65 66 3d 22 76 74 61 62 2e 68 74  <a href="vtab.ht
bb60: 6d 6c 23 78 66 69 6c 74 65 72 22 3e 78 46 69 6c  ml#xfilter">xFil
bb70: 74 65 72 3c 2f 61 3e 20 6d 65 74 68 6f 64 2c 20  ter</a> method, 
bb80: 74 68 65 6e 20 74 68 65 20 72 65 71 75 69 72 65  then the require
bb90: 64 20 62 69 74 73 20 6d 75 73 74 20 62 65 20 65  d bits must be e
bba0: 6e 63 6f 64 65 64 20 69 6e 74 6f 20 65 69 74 68  ncoded into eith
bbb0: 65 72 0a 74 68 65 20 69 64 78 4e 75 6d 20 6f 72  er.the idxNum or
bbc0: 20 69 64 78 53 74 72 20 6f 75 74 70 75 74 20 66   idxStr output f
bbd0: 69 65 6c 64 73 2e 0a 0a 3c 2f 70 3e 3c 68 33 20  ields...</p><h3 
bbe0: 69 64 3d 22 6f 75 74 70 75 74 73 22 3e 3c 73 70  id="outputs"><sp
bbf0: 61 6e 3e 32 2e 33 2e 32 2e 20 3c 2f 73 70 61 6e  an>2.3.2. </span
bc00: 3e 4f 75 74 70 75 74 73 3c 2f 68 33 3e 0a 0a 3c  >Outputs</h3>..<
bc10: 70 3e 47 69 76 65 6e 20 61 6c 6c 20 6f 66 20 74  p>Given all of t
bc20: 68 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  he information a
bc30: 62 6f 76 65 2c 20 74 68 65 20 6a 6f 62 20 6f 66  bove, the job of
bc40: 20 74 68 65 20 78 42 65 73 74 49 6e 64 65 78 20   the xBestIndex 
bc50: 0a 6d 65 74 68 6f 64 20 69 74 20 74 6f 20 66 69  .method it to fi
bc60: 67 75 72 65 20 6f 75 74 20 74 68 65 20 62 65 73  gure out the bes
bc70: 74 20 77 61 79 20 74 6f 20 73 65 61 72 63 68 20  t way to search 
bc80: 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
bc90: 65 2e 0a 0a 3c 2f 70 3e 3c 70 3e 54 68 65 20 78  e...</p><p>The x
bca0: 42 65 73 74 49 6e 64 65 78 20 6d 65 74 68 6f 64  BestIndex method
bcb0: 20 66 69 6c 6c 73 20 74 68 65 20 69 64 78 4e 75   fills the idxNu
bcc0: 6d 20 61 6e 64 20 69 64 78 53 74 72 20 66 69 65  m and idxStr fie
bcd0: 6c 64 73 20 77 69 74 68 20 0a 69 6e 66 6f 72 6d  lds with .inform
bce0: 61 74 69 6f 6e 20 74 68 61 74 20 63 6f 6d 6d 75  ation that commu
bcf0: 6e 69 63 61 74 65 73 20 61 6e 20 69 6e 64 65 78  nicates an index
bd00: 69 6e 67 20 73 74 72 61 74 65 67 79 20 74 6f 20  ing strategy to 
bd10: 74 68 65 20 3c 61 20 68 72 65 66 3d 22 76 74 61  the <a href="vta
bd20: 62 2e 68 74 6d 6c 23 78 66 69 6c 74 65 72 22 3e  b.html#xfilter">
bd30: 78 46 69 6c 74 65 72 3c 2f 61 3e 20 0a 6d 65 74  xFilter</a> .met
bd40: 68 6f 64 2e 20 54 68 65 20 69 6e 66 6f 72 6d 61  hod. The informa
bd50: 74 69 6f 6e 20 69 6e 20 69 64 78 4e 75 6d 20 61  tion in idxNum a
bd60: 6e 64 20 69 64 78 53 74 72 20 69 73 20 61 72 62  nd idxStr is arb
bd70: 69 74 72 61 72 79 20 61 73 20 66 61 72 20 0a 61  itrary as far .a
bd80: 73 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  s the SQLite cor
bd90: 65 20 69 73 20 63 6f 6e 63 65 72 6e 65 64 2e 20  e is concerned. 
bda0: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
bdb0: 6a 75 73 74 20 63 6f 70 69 65 73 20 74 68 65 20  just copies the 
bdc0: 0a 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 74 68 72  .information thr
bdd0: 6f 75 67 68 20 74 6f 20 74 68 65 20 3c 61 20 68  ough to the <a h
bde0: 72 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23 78  ref="vtab.html#x
bdf0: 66 69 6c 74 65 72 22 3e 78 46 69 6c 74 65 72 3c  filter">xFilter<
be00: 2f 61 3e 20 6d 65 74 68 6f 64 2e 20 41 6e 79 20  /a> method. Any 
be10: 64 65 73 69 72 65 64 20 6d 65 61 6e 69 6e 67 20  desired meaning 
be20: 63 61 6e 20 0a 62 65 20 61 73 73 69 67 6e 65 64  can .be assigned
be30: 20 74 6f 20 69 64 78 4e 75 6d 20 61 6e 64 20 69   to idxNum and i
be40: 64 78 53 74 72 20 61 73 20 6c 6f 6e 67 20 61 73  dxStr as long as
be50: 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64 20   xBestIndex and 
be60: 78 46 69 6c 74 65 72 20 0a 61 67 72 65 65 20 6f  xFilter .agree o
be70: 6e 20 77 68 61 74 20 74 68 61 74 20 6d 65 61 6e  n what that mean
be80: 69 6e 67 20 69 73 2e 0a 0a 3c 2f 70 3e 3c 70 3e  ing is...</p><p>
be90: 54 68 65 20 69 64 78 53 74 72 20 76 61 6c 75 65  The idxStr value
bea0: 20 6d 61 79 20 62 65 20 61 20 73 74 72 69 6e 67   may be a string
beb0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
bec0: 6e 20 53 51 4c 69 74 65 0a 6d 65 6d 6f 72 79 20  n SQLite.memory 
bed0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74  allocation funct
bee0: 69 6f 6e 20 73 75 63 68 20 61 73 20 3c 61 20 68  ion such as <a h
bef0: 72 65 66 3d 22 63 33 72 65 66 2f 6d 70 72 69 6e  ref="c3ref/mprin
bf00: 74 66 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33  tf.html">sqlite3
bf10: 5f 6d 70 72 69 6e 74 66 28 29 3c 2f 61 3e 2e 20  _mprintf()</a>. 
bf20: 0a 49 66 20 74 68 69 73 20 69 73 20 74 68 65 20  .If this is the 
bf30: 63 61 73 65 2c 20 74 68 65 6e 20 74 68 65 20 6e  case, then the n
bf40: 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 20  eedToFreeIdxStr 
bf50: 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 65 74  flag must be set
bf60: 20 74 6f 20 0a 74 72 75 65 20 73 6f 20 74 68 61   to .true so tha
bf70: 74 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  t the SQLite cor
bf80: 65 20 77 69 6c 6c 20 6b 6e 6f 77 20 74 6f 20 63  e will know to c
bf90: 61 6c 6c 20 3c 61 20 68 72 65 66 3d 22 63 33 72  all <a href="c3r
bfa0: 65 66 2f 66 72 65 65 2e 68 74 6d 6c 22 3e 73 71  ef/free.html">sq
bfb0: 6c 69 74 65 33 5f 66 72 65 65 28 29 3c 2f 61 3e  lite3_free()</a>
bfc0: 20 6f 6e 20 0a 74 68 61 74 20 73 74 72 69 6e 67   on .that string
bfd0: 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e   when it has fin
bfe0: 69 73 68 65 64 20 77 69 74 68 20 69 74 2c 20 61  ished with it, a
bff0: 6e 64 20 74 68 75 73 20 61 76 6f 69 64 20 61 20  nd thus avoid a 
c000: 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 0a 3c 2f  memory leak...</
c010: 70 3e 3c 70 3e 49 66 20 74 68 65 20 76 69 72 74  p><p>If the virt
c020: 75 61 6c 20 74 61 62 6c 65 20 77 69 6c 6c 20 6f  ual table will o
c030: 75 74 70 75 74 20 72 6f 77 73 20 69 6e 20 74 68  utput rows in th
c040: 65 20 6f 72 64 65 72 20 73 70 65 63 69 66 69 65  e order specifie
c050: 64 20 62 79 20 0a 74 68 65 20 4f 52 44 45 52 20  d by .the ORDER 
c060: 42 59 20 63 6c 61 75 73 65 2c 20 74 68 65 6e 20  BY clause, then 
c070: 74 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75  the orderByConsu
c080: 6d 65 64 20 66 6c 61 67 20 6d 61 79 20 62 65 20  med flag may be 
c090: 73 65 74 20 74 6f 20 0a 74 72 75 65 2e 20 49 66  set to .true. If
c0a0: 20 74 68 65 20 6f 75 74 70 75 74 20 69 73 20 6e   the output is n
c0b0: 6f 74 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ot automatically
c0c0: 20 69 6e 20 74 68 65 20 63 6f 72 72 65 63 74 20   in the correct 
c0d0: 6f 72 64 65 72 20 0a 74 68 65 6e 20 6f 72 64 65  order .then orde
c0e0: 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 75 73 74  rByConsumed must
c0f0: 20 62 65 20 6c 65 66 74 20 69 6e 20 69 74 73 20   be left in its 
c100: 64 65 66 61 75 6c 74 20 66 61 6c 73 65 20 73 65  default false se
c110: 74 74 69 6e 67 2e 20 0a 54 68 69 73 20 77 69 6c  tting. .This wil
c120: 6c 20 69 6e 64 69 63 61 74 65 20 74 6f 20 74 68  l indicate to th
c130: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 74 68  e SQLite core th
c140: 61 74 20 69 74 20 77 69 6c 6c 20 6e 65 65 64 20  at it will need 
c150: 74 6f 20 64 6f 20 61 20 0a 73 65 70 61 72 61 74  to do a .separat
c160: 65 20 73 6f 72 74 69 6e 67 20 70 61 73 73 20 6f  e sorting pass o
c170: 76 65 72 20 74 68 65 20 64 61 74 61 20 61 66 74  ver the data aft
c180: 65 72 20 69 74 20 63 6f 6d 65 73 20 6f 75 74 20  er it comes out 
c190: 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  of the virtual t
c1a0: 61 62 6c 65 2e 0a 0a 3c 2f 70 3e 3c 70 3e 54 68  able...</p><p>Th
c1b0: 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 20  e estimatedCost 
c1c0: 66 69 65 6c 64 20 73 68 6f 75 6c 64 20 62 65 20  field should be 
c1d0: 73 65 74 20 74 6f 20 74 68 65 20 65 73 74 69 6d  set to the estim
c1e0: 61 74 65 64 20 6e 75 6d 62 65 72 0a 6f 66 20 64  ated number.of d
c1f0: 69 73 6b 20 61 63 63 65 73 73 20 6f 70 65 72 61  isk access opera
c200: 74 69 6f 6e 73 20 72 65 71 75 69 72 65 64 20 74  tions required t
c210: 6f 20 65 78 65 63 75 74 65 20 74 68 69 73 20 71  o execute this q
c220: 75 65 72 79 20 61 67 61 69 6e 73 74 20 0a 74 68  uery against .th
c230: 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e  e virtual table.
c240: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
c250: 20 77 69 6c 6c 20 6f 66 74 65 6e 20 63 61 6c 6c   will often call
c260: 20 78 42 65 73 74 49 6e 64 65 78 20 0a 6d 75 6c   xBestIndex .mul
c270: 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68  tiple times with
c280: 20 64 69 66 66 65 72 65 6e 74 20 63 6f 6e 73 74   different const
c290: 72 61 69 6e 74 73 2c 20 6f 62 74 61 69 6e 20 6d  raints, obtain m
c2a0: 75 6c 74 69 70 6c 65 20 63 6f 73 74 0a 65 73 74  ultiple cost.est
c2b0: 69 6d 61 74 65 73 2c 20 74 68 65 6e 20 63 68 6f  imates, then cho
c2c0: 6f 73 65 20 74 68 65 20 71 75 65 72 79 20 70 6c  ose the query pl
c2d0: 61 6e 20 74 68 61 74 20 67 69 76 65 73 20 74 68  an that gives th
c2e0: 65 20 6c 6f 77 65 73 74 20 65 73 74 69 6d 61 74  e lowest estimat
c2f0: 65 2e 0a 0a 3c 2f 70 3e 3c 70 3e 49 66 20 74 68  e...</p><p>If th
c300: 65 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f  e current versio
c310: 6e 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 33  n of SQLite is 3
c320: 2e 38 2e 32 20 6f 72 20 67 72 65 61 74 65 72 2c  .8.2 or greater,
c330: 20 74 68 65 20 65 73 74 69 6d 61 74 65 64 52 6f   the estimatedRo
c340: 77 73 0a 66 69 65 6c 64 20 6d 61 79 20 62 65 20  ws.field may be 
c350: 73 65 74 20 74 6f 20 61 6e 20 65 73 74 69 6d 61  set to an estima
c360: 74 65 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  te of the number
c370: 20 6f 66 20 72 6f 77 73 20 72 65 74 75 72 6e 65   of rows returne
c380: 64 20 62 79 20 74 68 65 0a 70 72 6f 70 6f 73 65  d by the.propose
c390: 64 20 71 75 65 72 79 20 70 6c 61 6e 2e 20 49 66  d query plan. If
c3a0: 20 74 68 69 73 20 76 61 6c 75 65 20 69 73 20 6e   this value is n
c3b0: 6f 74 20 65 78 70 6c 69 63 69 74 6c 79 20 73 65  ot explicitly se
c3c0: 74 2c 20 74 68 65 20 64 65 66 61 75 6c 74 20 0a  t, the default .
c3d0: 65 73 74 69 6d 61 74 65 20 6f 66 20 32 35 20 72  estimate of 25 r
c3e0: 6f 77 73 20 69 73 20 75 73 65 64 2e 0a 0a 3c 2f  ows is used...</
c3f0: 70 3e 3c 70 3e 49 66 20 74 68 65 20 63 75 72 72  p><p>If the curr
c400: 65 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 53  ent version of S
c410: 51 4c 69 74 65 20 69 73 20 33 2e 39 2e 30 20 6f  QLite is 3.9.0 o
c420: 72 20 67 72 65 61 74 65 72 2c 20 74 68 65 20 69  r greater, the i
c430: 64 78 46 6c 61 67 73 20 66 69 65 6c 64 0a 6d 61  dxFlags field.ma
c440: 79 20 62 65 20 73 65 74 20 74 6f 20 53 51 4c 49  y be set to SQLI
c450: 54 45 5f 49 4e 44 45 58 5f 53 43 41 4e 5f 55 4e  TE_INDEX_SCAN_UN
c460: 49 51 55 45 20 74 6f 20 69 6e 64 69 63 61 74 65  IQUE to indicate
c470: 20 74 68 61 74 20 74 68 65 20 76 69 72 74 75 61   that the virtua
c480: 6c 20 74 61 62 6c 65 0a 77 69 6c 6c 20 72 65 74  l table.will ret
c490: 75 72 6e 20 6f 6e 6c 79 20 7a 65 72 6f 20 6f 72  urn only zero or
c4a0: 20 6f 6e 65 20 72 6f 77 73 20 67 69 76 65 6e 20   one rows given 
c4b0: 74 68 65 20 69 6e 70 75 74 20 63 6f 6e 73 74 72  the input constr
c4c0: 61 69 6e 74 73 2e 20 20 41 64 64 69 74 69 6f 6e  aints.  Addition
c4d0: 61 6c 0a 62 69 74 73 20 6f 66 20 74 68 65 20 69  al.bits of the i
c4e0: 64 78 46 6c 61 67 73 20 66 69 65 6c 64 20 6d 69  dxFlags field mi
c4f0: 67 68 74 20 62 65 20 75 6e 64 65 72 73 74 6f 6f  ght be understoo
c500: 64 20 69 6e 20 6c 61 74 65 72 20 76 65 72 73 69  d in later versi
c510: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 0a  ons of SQLite...
c520: 3c 2f 70 3e 3c 70 3e 54 68 65 20 61 43 6f 6e 73  </p><p>The aCons
c530: 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 61 72  traintUsage[] ar
c540: 72 61 79 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 65  ray contains one
c550: 20 65 6c 65 6d 65 6e 74 20 66 6f 72 20 65 61 63   element for eac
c560: 68 20 6f 66 20 0a 74 68 65 20 6e 43 6f 6e 73 74  h of .the nConst
c570: 72 61 69 6e 74 20 63 6f 6e 73 74 72 61 69 6e 74  raint constraint
c580: 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 73 20  s in the inputs 
c590: 73 65 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 0a  section of the .
c5a0: 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f 69  <a href="c3ref/i
c5b0: 6e 64 65 78 5f 69 6e 66 6f 2e 68 74 6d 6c 22 3e  ndex_info.html">
c5c0: 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
c5d0: 66 6f 3c 2f 61 3e 20 73 74 72 75 63 74 75 72 65  fo</a> structure
c5e0: 2e 20 0a 54 68 65 20 61 43 6f 6e 73 74 72 61 69  . .The aConstrai
c5f0: 6e 74 55 73 61 67 65 5b 5d 20 61 72 72 61 79 20  ntUsage[] array 
c600: 69 73 20 75 73 65 64 20 62 79 20 78 42 65 73 74  is used by xBest
c610: 49 6e 64 65 78 20 74 6f 20 74 65 6c 6c 20 74 68  Index to tell th
c620: 65 20 0a 63 6f 72 65 20 68 6f 77 20 69 74 20 69  e .core how it i
c630: 73 20 75 73 69 6e 67 20 74 68 65 20 63 6f 6e 73  s using the cons
c640: 74 72 61 69 6e 74 73 2e 0a 0a 3c 2f 70 3e 3c 70  traints...</p><p
c650: 3e 54 68 65 20 78 42 65 73 74 49 6e 64 65 78 20  >The xBestIndex 
c660: 6d 65 74 68 6f 64 20 6d 61 79 20 73 65 74 20 61  method may set a
c670: 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b  ConstraintUsage[
c680: 5d 2e 61 72 67 76 49 6e 64 65 78 20 0a 65 6e 74  ].argvIndex .ent
c690: 72 69 65 73 20 74 6f 20 76 61 6c 75 65 73 20 67  ries to values g
c6a0: 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
c6b0: 2e 20 0a 45 78 61 63 74 6c 79 20 6f 6e 65 20 65  . .Exactly one e
c6c0: 6e 74 72 79 20 73 68 6f 75 6c 64 20 62 65 20 73  ntry should be s
c6d0: 65 74 20 74 6f 20 31 2c 20 61 6e 6f 74 68 65 72  et to 1, another
c6e0: 20 74 6f 20 32 2c 20 61 6e 6f 74 68 65 72 20 74   to 2, another t
c6f0: 6f 20 33 2c 20 0a 61 6e 64 20 73 6f 20 66 6f 72  o 3, .and so for
c700: 74 68 20 75 70 20 74 6f 20 61 73 20 6d 61 6e 79  th up to as many
c710: 20 6f 72 20 61 73 20 66 65 77 20 61 73 20 74 68   or as few as th
c720: 65 20 78 42 65 73 74 49 6e 64 65 78 20 6d 65 74  e xBestIndex met
c730: 68 6f 64 20 77 61 6e 74 73 2e 20 0a 54 68 65 20  hod wants. .The 
c740: 45 58 50 52 20 6f 66 20 74 68 65 20 63 6f 72 72  EXPR of the corr
c750: 65 73 70 6f 6e 64 69 6e 67 20 63 6f 6e 73 74 72  esponding constr
c760: 61 69 6e 74 73 20 77 69 6c 6c 20 74 68 65 6e 20  aints will then 
c770: 62 65 20 70 61 73 73 65 64 20 0a 69 6e 20 61 73  be passed .in as
c780: 20 74 68 65 20 61 72 67 76 5b 5d 20 70 61 72 61   the argv[] para
c790: 6d 65 74 65 72 73 20 74 6f 20 78 46 69 6c 74 65  meters to xFilte
c7a0: 72 2e 0a 0a 3c 2f 70 3e 3c 70 3e 46 6f 72 20 65  r...</p><p>For e
c7b0: 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 61  xample, if the a
c7c0: 43 6f 6e 73 74 72 61 69 6e 74 5b 33 5d 2e 61 72  Constraint[3].ar
c7d0: 67 76 49 6e 64 65 78 20 69 73 20 73 65 74 20 74  gvIndex is set t
c7e0: 6f 20 31 2c 20 74 68 65 6e 20 0a 77 68 65 6e 20  o 1, then .when 
c7f0: 78 46 69 6c 74 65 72 20 69 73 20 63 61 6c 6c 65  xFilter is calle
c800: 64 2c 20 74 68 65 20 61 72 67 76 5b 30 5d 20 70  d, the argv[0] p
c810: 61 73 73 65 64 20 74 6f 20 78 46 69 6c 74 65 72  assed to xFilter
c820: 20 77 69 6c 6c 20 68 61 76 65 20 0a 74 68 65 20   will have .the 
c830: 45 58 50 52 20 76 61 6c 75 65 20 6f 66 20 74 68  EXPR value of th
c840: 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 33 5d  e aConstraint[3]
c850: 20 63 6f 6e 73 74 72 61 69 6e 74 2e 0a 0a 3c 2f   constraint...</
c860: 70 3e 3c 70 3e 42 79 20 64 65 66 61 75 6c 74 2c  p><p>By default,
c870: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
c880: 20 64 6f 75 62 6c 65 20 63 68 65 63 6b 73 20 61   double checks a
c890: 6c 6c 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f  ll constraints o
c8a0: 6e 20 0a 65 61 63 68 20 72 6f 77 20 6f 66 20 74  n .each row of t
c8b0: 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
c8c0: 20 74 68 61 74 20 69 74 20 72 65 63 65 69 76 65   that it receive
c8d0: 73 2e 20 49 66 20 73 75 63 68 20 61 20 63 68 65  s. If such a che
c8e0: 63 6b 20 0a 69 73 20 72 65 64 75 6e 64 61 6e 74  ck .is redundant
c8f0: 2c 20 74 68 65 20 78 42 65 73 74 46 69 6c 74 65  , the xBestFilte
c900: 72 20 6d 65 74 68 6f 64 20 63 61 6e 20 73 75 70  r method can sup
c910: 70 72 65 73 73 20 74 68 61 74 20 64 6f 75 62 6c  press that doubl
c920: 65 2d 63 68 65 63 6b 20 62 79 20 0a 73 65 74 74  e-check by .sett
c930: 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 55  ing aConstraintU
c940: 73 61 67 65 5b 5d 2e 6f 6d 69 74 2e 0a 0a 3c 61  sage[].omit...<a
c950: 20 6e 61 6d 65 3d 22 78 64 69 73 63 6f 6e 6e 65   name="xdisconne
c960: 63 74 22 3e 3c 2f 61 3e 0a 0a 3c 2f 70 3e 3c 68  ct"></a>..</p><h
c970: 32 20 69 64 3d 22 74 68 65 5f 78 64 69 73 63 6f  2 id="the_xdisco
c980: 6e 6e 65 63 74 5f 6d 65 74 68 6f 64 22 3e 3c 73  nnect_method"><s
c990: 70 61 6e 3e 32 2e 34 2e 20 3c 2f 73 70 61 6e 3e  pan>2.4. </span>
c9a0: 54 68 65 20 78 44 69 73 63 6f 6e 6e 65 63 74 20  The xDisconnect 
c9b0: 4d 65 74 68 6f 64 3c 2f 68 32 3e 0a 0a 3c 64 69  Method</h2>..<di
c9c0: 76 20 63 6c 61 73 73 3d 22 63 6f 64 65 62 6c 6f  v class="codeblo
c9d0: 63 6b 22 3e 3c 70 72 65 3e 69 6e 74 20 28 2a 78  ck"><pre>int (*x
c9e0: 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69  Disconnect)(sqli
c9f0: 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
ca00: 3b 0a 3c 2f 70 72 65 3e 3c 2f 64 69 76 3e 0a 0a  ;.</pre></div>..
ca10: 3c 70 3e 54 68 69 73 20 6d 65 74 68 6f 64 20 72  <p>This method r
ca20: 65 6c 65 61 73 65 73 20 61 20 63 6f 6e 6e 65 63  eleases a connec
ca30: 74 69 6f 6e 20 74 6f 20 61 20 76 69 72 74 75 61  tion to a virtua
ca40: 6c 20 74 61 62 6c 65 2e 20 0a 4f 6e 6c 79 20 74  l table. .Only t
ca50: 68 65 20 3c 61 20 68 72 65 66 3d 22 63 33 72 65  he <a href="c3re
ca60: 66 2f 76 74 61 62 2e 68 74 6d 6c 22 3e 73 71 6c  f/vtab.html">sql
ca70: 69 74 65 33 5f 76 74 61 62 3c 2f 61 3e 20 6f 62  ite3_vtab</a> ob
ca80: 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f 79 65  ject is destroye
ca90: 64 2e 0a 54 68 65 20 76 69 72 74 75 61 6c 20 74  d..The virtual t
caa0: 61 62 6c 65 20 69 73 20 6e 6f 74 20 64 65 73 74  able is not dest
cab0: 72 6f 79 65 64 20 61 6e 64 20 61 6e 79 20 62 61  royed and any ba
cac0: 63 6b 69 6e 67 20 73 74 6f 72 65 20 0a 61 73 73  cking store .ass
cad0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
cae0: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 70   virtual table p
caf0: 65 72 73 69 73 74 73 2e 20 0a 0a 54 68 69 73 20  ersists. ..This 
cb00: 6d 65 74 68 6f 64 20 75 6e 64 6f 65 73 20 74 68  method undoes th
cb10: 65 20 77 6f 72 6b 20 6f 66 20 3c 61 20 68 72 65  e work of <a hre
cb20: 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23 78 63 6f  f="vtab.html#xco
cb30: 6e 6e 65 63 74 22 3e 78 43 6f 6e 6e 65 63 74 3c  nnect">xConnect<
cb40: 2f 61 3e 2e 0a 0a 3c 2f 70 3e 3c 70 3e 54 68 69  /a>...</p><p>Thi
cb50: 73 20 6d 65 74 68 6f 64 20 69 73 20 61 20 64 65  s method is a de
cb60: 73 74 72 75 63 74 6f 72 20 66 6f 72 20 61 20 63  structor for a c
cb70: 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65  onnection to the
cb80: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 0a   virtual table..
cb90: 43 6f 6e 74 72 61 73 74 20 74 68 69 73 20 6d 65  Contrast this me
cba0: 74 68 6f 64 20 77 69 74 68 20 3c 61 20 68 72 65  thod with <a hre
cbb0: 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23 73 71 6c  f="vtab.html#sql
cbc0: 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 44 65 73  ite3_module.xDes
cbd0: 74 72 6f 79 22 3e 78 44 65 73 74 72 6f 79 3c 2f  troy">xDestroy</
cbe0: 61 3e 2e 20 20 54 68 65 20 78 44 65 73 74 72 6f  a>.  The xDestro
cbf0: 79 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  y is a destructo
cc00: 72 0a 66 6f 72 20 74 68 65 20 65 6e 74 69 72 65  r.for the entire
cc10: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 0a   virtual table..
cc20: 0a 3c 2f 70 3e 3c 70 3e 54 68 65 20 78 44 69 73  .</p><p>The xDis
cc30: 63 6f 6e 6e 65 63 74 20 6d 65 74 68 6f 64 20 69  connect method i
cc40: 73 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65  s required for e
cc50: 76 65 72 79 20 76 69 72 74 75 61 6c 20 74 61 62  very virtual tab
cc60: 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
cc70: 6e 2c 0a 74 68 6f 75 67 68 20 69 74 20 69 73 20  n,.though it is 
cc80: 61 63 63 65 70 74 61 62 6c 65 20 66 6f 72 20 74  acceptable for t
cc90: 68 65 20 78 44 69 73 63 6f 6e 6e 65 63 74 20 61  he xDisconnect a
cca0: 6e 64 20 3c 61 20 68 72 65 66 3d 22 76 74 61 62  nd <a href="vtab
ccb0: 2e 68 74 6d 6c 23 73 71 6c 69 74 65 33 5f 6d 6f  .html#sqlite3_mo
ccc0: 64 75 6c 65 2e 78 44 65 73 74 72 6f 79 22 3e 78  dule.xDestroy">x
ccd0: 44 65 73 74 72 6f 79 3c 2f 61 3e 20 6d 65 74 68  Destroy</a> meth
cce0: 6f 64 73 20 74 6f 20 62 65 0a 74 68 65 20 73 61  ods to be.the sa
ccf0: 6d 65 20 66 75 6e 63 74 69 6f 6e 20 69 66 20 74  me function if t
cd00: 68 61 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20  hat makes sense 
cd10: 66 6f 72 20 74 68 65 20 70 61 72 74 69 63 75 6c  for the particul
cd20: 61 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ar virtual table
cd30: 2e 0a 0a 3c 61 20 6e 61 6d 65 3d 22 73 71 6c 69  ...<a name="sqli
cd40: 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 44 65 73 74  te3_module.xDest
cd50: 72 6f 79 22 3e 3c 2f 61 3e 0a 0a 3c 2f 70 3e 3c  roy"></a>..</p><
cd60: 68 32 20 69 64 3d 22 74 68 65 5f 78 64 65 73 74  h2 id="the_xdest
cd70: 72 6f 79 5f 6d 65 74 68 6f 64 22 3e 3c 73 70 61  roy_method"><spa
cd80: 6e 3e 32 2e 35 2e 20 3c 2f 73 70 61 6e 3e 54 68  n>2.5. </span>Th
cd90: 65 20 78 44 65 73 74 72 6f 79 20 4d 65 74 68 6f  e xDestroy Metho
cda0: 64 3c 2f 68 32 3e 0a 0a 3c 64 69 76 20 63 6c 61  d</h2>..<div cla
cdb0: 73 73 3d 22 63 6f 64 65 62 6c 6f 63 6b 22 3e 3c  ss="codeblock"><
cdc0: 70 72 65 3e 69 6e 74 20 28 2a 78 44 65 73 74 72  pre>int (*xDestr
cdd0: 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  oy)(sqlite3_vtab
cde0: 20 2a 70 56 54 61 62 29 3b 0a 3c 2f 70 72 65 3e   *pVTab);.</pre>
cdf0: 3c 2f 64 69 76 3e 0a 0a 3c 70 3e 54 68 69 73 20  </div>..<p>This 
ce00: 6d 65 74 68 6f 64 20 72 65 6c 65 61 73 65 73 20  method releases 
ce10: 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  a connection to 
ce20: 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2c  a virtual table,
ce30: 20 6a 75 73 74 20 6c 69 6b 65 20 0a 74 68 65 20   just like .the 
ce40: 3c 61 20 68 72 65 66 3d 22 76 74 61 62 2e 68 74  <a href="vtab.ht
ce50: 6d 6c 23 78 64 69 73 63 6f 6e 6e 65 63 74 22 3e  ml#xdisconnect">
ce60: 78 44 69 73 63 6f 6e 6e 65 63 74 3c 2f 61 3e 20  xDisconnect</a> 
ce70: 6d 65 74 68 6f 64 2c 20 61 6e 64 20 69 74 20 61  method, and it a
ce80: 6c 73 6f 20 64 65 73 74 72 6f 79 73 20 74 68 65  lso destroys the
ce90: 20 75 6e 64 65 72 6c 79 69 6e 67 20 0a 74 61 62   underlying .tab
cea0: 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
ceb0: 6e 2e 20 54 68 69 73 20 6d 65 74 68 6f 64 20 75  n. This method u
cec0: 6e 64 6f 65 73 20 74 68 65 20 77 6f 72 6b 20 6f  ndoes the work o
ced0: 66 20 3c 61 20 68 72 65 66 3d 22 76 74 61 62 2e  f <a href="vtab.
cee0: 68 74 6d 6c 23 78 63 72 65 61 74 65 22 3e 78 43  html#xcreate">xC
cef0: 72 65 61 74 65 3c 2f 61 3e 2e 0a 0a 3c 2f 70 3e  reate</a>...</p>
cf00: 3c 70 3e 54 68 65 20 3c 61 20 68 72 65 66 3d 22  <p>The <a href="
cf10: 76 74 61 62 2e 68 74 6d 6c 23 78 64 69 73 63 6f  vtab.html#xdisco
cf20: 6e 6e 65 63 74 22 3e 78 44 69 73 63 6f 6e 6e 65  nnect">xDisconne
cf30: 63 74 3c 2f 61 3e 20 6d 65 74 68 6f 64 20 69 73  ct</a> method is
cf40: 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76 65 72   called whenever
cf50: 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
cf60: 65 63 74 69 6f 6e 0a 74 68 61 74 20 75 73 65 73  ection.that uses
cf70: 20 61 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65   a virtual table
cf80: 20 69 73 20 63 6c 6f 73 65 64 2e 20 54 68 65 20   is closed. The 
cf90: 78 44 65 73 74 72 6f 79 20 6d 65 74 68 6f 64 20  xDestroy method 
cfa0: 69 73 20 6f 6e 6c 79 20 0a 63 61 6c 6c 65 64 20  is only .called 
cfb0: 77 68 65 6e 20 61 20 3c 61 20 68 72 65 66 3d 22  when a <a href="
cfc0: 6c 61 6e 67 5f 64 72 6f 70 74 61 62 6c 65 2e 68  lang_droptable.h
cfd0: 74 6d 6c 22 3e 44 52 4f 50 20 54 41 42 4c 45 3c  tml">DROP TABLE<
cfe0: 2f 61 3e 20 73 74 61 74 65 6d 65 6e 74 20 69 73  /a> statement is
cff0: 20 65 78 65 63 75 74 65 64 20 61 67 61 69 6e 73   executed agains
d000: 74 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  t the virtual ta
d010: 62 6c 65 2e 0a 0a 3c 2f 70 3e 3c 70 3e 54 68 65  ble...</p><p>The
d020: 20 78 44 65 73 74 72 6f 79 20 6d 65 74 68 6f 64   xDestroy method
d030: 20 69 73 20 72 65 71 75 69 72 65 64 20 66 6f 72   is required for
d040: 20 65 76 65 72 79 20 76 69 72 74 75 61 6c 20 74   every virtual t
d050: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
d060: 69 6f 6e 2c 0a 74 68 6f 75 67 68 20 69 74 20 69  ion,.though it i
d070: 73 20 61 63 63 65 70 74 61 62 6c 65 20 66 6f 72  s acceptable for
d080: 20 74 68 65 20 3c 61 20 68 72 65 66 3d 22 76 74   the <a href="vt
d090: 61 62 2e 68 74 6d 6c 23 78 64 69 73 63 6f 6e 6e  ab.html#xdisconn
d0a0: 65 63 74 22 3e 78 44 69 73 63 6f 6e 6e 65 63 74  ect">xDisconnect
d0b0: 3c 2f 61 3e 20 61 6e 64 20 78 44 65 73 74 72 6f  </a> and xDestro
d0c0: 79 20 6d 65 74 68 6f 64 73 20 74 6f 20 62 65 0a  y methods to be.
d0d0: 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
d0e0: 6e 20 69 66 20 74 68 61 74 20 6d 61 6b 65 73 20  n if that makes 
d0f0: 73 65 6e 73 65 20 66 6f 72 20 74 68 65 20 70 61  sense for the pa
d100: 72 74 69 63 75 6c 61 72 20 76 69 72 74 75 61 6c  rticular virtual
d110: 20 74 61 62 6c 65 2e 0a 0a 3c 61 20 6e 61 6d 65   table...<a name
d120: 3d 22 78 6f 70 65 6e 22 3e 3c 2f 61 3e 0a 0a 3c  ="xopen"></a>..<
d130: 2f 70 3e 3c 68 32 20 69 64 3d 22 74 68 65 5f 78  /p><h2 id="the_x
d140: 6f 70 65 6e 5f 6d 65 74 68 6f 64 22 3e 3c 73 70  open_method"><sp
d150: 61 6e 3e 32 2e 36 2e 20 3c 2f 73 70 61 6e 3e 54  an>2.6. </span>T
d160: 68 65 20 78 4f 70 65 6e 20 4d 65 74 68 6f 64 3c  he xOpen Method<
d170: 2f 68 32 3e 0a 0a 3c 64 69 76 20 63 6c 61 73 73  /h2>..<div class
d180: 3d 22 63 6f 64 65 62 6c 6f 63 6b 22 3e 3c 70 72  ="codeblock"><pr
d190: 65 3e 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73  e>int (*xOpen)(s
d1a0: 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
d1b0: 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62  ab, sqlite3_vtab
d1c0: 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73  _cursor **ppCurs
d1d0: 6f 72 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 64 69 76  or);.</pre></div
d1e0: 3e 0a 0a 3c 70 3e 54 68 65 20 78 4f 70 65 6e 20  >..<p>The xOpen 
d1f0: 6d 65 74 68 6f 64 20 63 72 65 61 74 65 73 20 61  method creates a
d200: 20 6e 65 77 20 63 75 72 73 6f 72 20 75 73 65 64   new cursor used
d210: 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20 28   for accessing (
d220: 72 65 61 64 20 61 6e 64 2f 6f 72 0a 77 72 69 74  read and/or.writ
d230: 69 6e 67 29 20 61 20 76 69 72 74 75 61 6c 20 74  ing) a virtual t
d240: 61 62 6c 65 2e 20 20 41 20 73 75 63 63 65 73 73  able.  A success
d250: 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
d260: 66 20 74 68 69 73 20 6d 65 74 68 6f 64 20 0a 77  f this method .w
d270: 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  ill allocate the
d280: 20 6d 65 6d 6f 72 79 20 66 6f 72 20 74 68 65 20   memory for the 
d290: 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f 76  <a href="c3ref/v
d2a0: 74 61 62 5f 63 75 72 73 6f 72 2e 68 74 6d 6c 22  tab_cursor.html"
d2b0: 3e 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  >sqlite3_vtab_cu
d2c0: 72 73 6f 72 3c 2f 61 3e 20 28 6f 72 20 61 20 73  rsor</a> (or a s
d2d0: 75 62 63 6c 61 73 73 29 2c 0a 69 6e 69 74 69 61  ubclass),.initia
d2e0: 6c 69 7a 65 20 74 68 65 20 6e 65 77 20 6f 62 6a  lize the new obj
d2f0: 65 63 74 2c 20 61 6e 64 20 6d 61 6b 65 20 2a 70  ect, and make *p
d300: 70 43 75 72 73 6f 72 20 70 6f 69 6e 74 20 74 6f  pCursor point to
d310: 20 74 68 65 20 6e 65 77 20 6f 62 6a 65 63 74 2e   the new object.
d320: 0a 54 68 65 20 73 75 63 63 65 73 73 66 75 6c 20  .The successful 
d330: 63 61 6c 6c 20 74 68 65 6e 20 72 65 74 75 72 6e  call then return
d340: 73 20 3c 61 20 68 72 65 66 3d 22 72 65 73 63 6f  s <a href="resco
d350: 64 65 2e 68 74 6d 6c 23 6f 6b 22 3e 53 51 4c 49  de.html#ok">SQLI
d360: 54 45 5f 4f 4b 3c 2f 61 3e 2e 0a 0a 3c 2f 70 3e  TE_OK</a>...</p>
d370: 3c 70 3e 46 6f 72 20 65 76 65 72 79 20 73 75 63  <p>For every suc
d380: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
d390: 74 68 69 73 20 6d 65 74 68 6f 64 2c 20 74 68 65  this method, the
d3a0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c   SQLite core wil
d3b0: 6c 0a 6c 61 74 65 72 20 69 6e 76 6f 6b 65 20 74  l.later invoke t
d3c0: 68 65 20 3c 61 20 68 72 65 66 3d 22 76 74 61 62  he <a href="vtab
d3d0: 2e 68 74 6d 6c 23 78 63 6c 6f 73 65 22 3e 78 43  .html#xclose">xC
d3e0: 6c 6f 73 65 3c 2f 61 3e 20 6d 65 74 68 6f 64 20  lose</a> method 
d3f0: 74 6f 20 64 65 73 74 72 6f 79 20 0a 74 68 65 20  to destroy .the 
d400: 61 6c 6c 6f 63 61 74 65 64 20 63 75 72 73 6f 72  allocated cursor
d410: 2e 0a 0a 3c 2f 70 3e 3c 70 3e 54 68 65 20 78 4f  ...</p><p>The xO
d420: 70 65 6e 20 6d 65 74 68 6f 64 20 6e 65 65 64 20  pen method need 
d430: 6e 6f 74 20 69 6e 69 74 69 61 6c 69 7a 65 20 74  not initialize t
d440: 68 65 20 70 56 74 61 62 20 66 69 65 6c 64 20 6f  he pVtab field o
d450: 66 20 74 68 65 0a 3c 61 20 68 72 65 66 3d 22 63  f the.<a href="c
d460: 33 72 65 66 2f 76 74 61 62 5f 63 75 72 73 6f 72  3ref/vtab_cursor
d470: 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 76  .html">sqlite3_v
d480: 74 61 62 5f 63 75 72 73 6f 72 3c 2f 61 3e 20 73  tab_cursor</a> s
d490: 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 53  tructure.  The S
d4a0: 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20  QLite core will 
d4b0: 74 61 6b 65 20 63 61 72 65 0a 6f 66 20 74 68 61  take care.of tha
d4c0: 74 20 63 68 6f 72 65 20 61 75 74 6f 6d 61 74 69  t chore automati
d4d0: 63 61 6c 6c 79 2e 0a 0a 3c 2f 70 3e 3c 70 3e 41  cally...</p><p>A
d4e0: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
d4f0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
d500: 73 74 20 62 65 20 61 62 6c 65 20 74 6f 20 73 75  st be able to su
d510: 70 70 6f 72 74 20 61 6e 20 61 72 62 69 74 72 61  pport an arbitra
d520: 72 79 0a 6e 75 6d 62 65 72 20 6f 66 20 73 69 6d  ry.number of sim
d530: 75 6c 74 61 6e 65 6f 75 73 6c 79 20 6f 70 65 6e  ultaneously open
d540: 20 63 75 72 73 6f 72 73 2e 0a 0a 3c 2f 70 3e 3c   cursors...</p><
d550: 70 3e 57 68 65 6e 20 69 6e 69 74 69 61 6c 6c 79  p>When initially
d560: 20 6f 70 65 6e 65 64 2c 20 74 68 65 20 63 75 72   opened, the cur
d570: 73 6f 72 20 69 73 20 69 6e 20 61 6e 20 75 6e 64  sor is in an und
d580: 65 66 69 6e 65 64 20 73 74 61 74 65 2e 0a 54 68  efined state..Th
d590: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
d5a0: 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 3c 61  ll invoke the <a
d5b0: 20 68 72 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c   href="vtab.html
d5c0: 23 78 66 69 6c 74 65 72 22 3e 78 46 69 6c 74 65  #xfilter">xFilte
d5d0: 72 3c 2f 61 3e 20 6d 65 74 68 6f 64 0a 6f 6e 20  r</a> method.on 
d5e0: 74 68 65 20 63 75 72 73 6f 72 20 70 72 69 6f 72  the cursor prior
d5f0: 20 74 6f 20 61 6e 79 20 61 74 74 65 6d 70 74 20   to any attempt 
d600: 74 6f 20 70 6f 73 69 74 69 6f 6e 20 6f 72 20 72  to position or r
d610: 65 61 64 20 66 72 6f 6d 20 74 68 65 20 63 75 72  ead from the cur
d620: 73 6f 72 2e 0a 0a 3c 2f 70 3e 3c 70 3e 54 68 65  sor...</p><p>The
d630: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 69 73   xOpen method is
d640: 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 76   required for ev
d650: 65 72 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c  ery virtual tabl
d660: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
d670: 2e 0a 0a 3c 61 20 6e 61 6d 65 3d 22 78 63 6c 6f  ...<a name="xclo
d680: 73 65 22 3e 3c 2f 61 3e 0a 0a 3c 2f 70 3e 3c 68  se"></a>..</p><h
d690: 32 20 69 64 3d 22 74 68 65 5f 78 63 6c 6f 73 65  2 id="the_xclose
d6a0: 5f 6d 65 74 68 6f 64 22 3e 3c 73 70 61 6e 3e 32  _method"><span>2
d6b0: 2e 37 2e 20 3c 2f 73 70 61 6e 3e 54 68 65 20 78  .7. </span>The x
d6c0: 43 6c 6f 73 65 20 4d 65 74 68 6f 64 3c 2f 68 32  Close Method</h2
d6d0: 3e 0a 0a 3c 64 69 76 20 63 6c 61 73 73 3d 22 63  >..<div class="c
d6e0: 6f 64 65 62 6c 6f 63 6b 22 3e 3c 70 72 65 3e 69  odeblock"><pre>i
d6f0: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
d700: 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
d710: 2a 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 64 69 76 3e  *);.</pre></div>
d720: 0a 0a 3c 70 3e 54 68 65 20 78 43 6c 6f 73 65 20  ..<p>The xClose 
d730: 6d 65 74 68 6f 64 20 63 6c 6f 73 65 73 20 61 20  method closes a 
d740: 63 75 72 73 6f 72 20 70 72 65 76 69 6f 75 73 6c  cursor previousl
d750: 79 20 6f 70 65 6e 65 64 20 62 79 20 0a 3c 61 20  y opened by .<a 
d760: 68 72 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23  href="vtab.html#
d770: 78 6f 70 65 6e 22 3e 78 4f 70 65 6e 3c 2f 61 3e  xopen">xOpen</a>
d780: 2e 20 0a 54 68 65 20 53 51 4c 69 74 65 20 63 6f  . .The SQLite co
d790: 72 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  re will always c
d7a0: 61 6c 6c 20 78 43 6c 6f 73 65 20 6f 6e 63 65 20  all xClose once 
d7b0: 66 6f 72 20 65 61 63 68 20 63 75 72 73 6f 72 20  for each cursor 
d7c0: 6f 70 65 6e 65 64 20 0a 75 73 69 6e 67 20 78 4f  opened .using xO
d7d0: 70 65 6e 2e 0a 0a 3c 2f 70 3e 3c 70 3e 54 68 69  pen...</p><p>Thi
d7e0: 73 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 72 65  s method must re
d7f0: 6c 65 61 73 65 20 61 6c 6c 20 72 65 73 6f 75 72  lease all resour
d800: 63 65 73 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ces allocated by
d810: 20 74 68 65 0a 63 6f 72 72 65 73 70 6f 6e 64 69   the.correspondi
d820: 6e 67 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 20 54  ng xOpen call. T
d830: 68 65 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  he routine will 
d840: 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
d850: 61 69 6e 20 65 76 65 6e 20 69 66 20 69 74 0a 72  ain even if it.r
d860: 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e  eturns an error.
d870: 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
d880: 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 74  e will not use t
d890: 68 65 0a 3c 61 20 68 72 65 66 3d 22 63 33 72 65  he.<a href="c3re
d8a0: 66 2f 76 74 61 62 5f 63 75 72 73 6f 72 2e 68 74  f/vtab_cursor.ht
d8b0: 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 76 74 61 62  ml">sqlite3_vtab
d8c0: 5f 63 75 72 73 6f 72 3c 2f 61 3e 20 61 67 61 69  _cursor</a> agai
d8d0: 6e 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  n after it has b
d8e0: 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 0a 3c 2f 70  een closed...</p
d8f0: 3e 3c 70 3e 54 68 65 20 78 43 6c 6f 73 65 20 6d  ><p>The xClose m
d900: 65 74 68 6f 64 20 69 73 20 72 65 71 75 69 72 65  ethod is require
d910: 64 20 66 6f 72 20 65 76 65 72 79 20 76 69 72 74  d for every virt
d920: 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
d930: 65 6e 74 61 74 69 6f 6e 2e 0a 0a 3c 61 20 6e 61  entation...<a na
d940: 6d 65 3d 22 78 65 6f 66 22 3e 3c 2f 61 3e 0a 0a  me="xeof"></a>..
d950: 3c 2f 70 3e 3c 68 32 20 69 64 3d 22 74 68 65 5f  </p><h2 id="the_
d960: 78 65 6f 66 5f 6d 65 74 68 6f 64 22 3e 3c 73 70  xeof_method"><sp
d970: 61 6e 3e 32 2e 38 2e 20 3c 2f 73 70 61 6e 3e 54  an>2.8. </span>T
d980: 68 65 20 78 45 6f 66 20 4d 65 74 68 6f 64 3c 2f  he xEof Method</
d990: 68 32 3e 0a 0a 3c 64 69 76 20 63 6c 61 73 73 3d  h2>..<div class=
d9a0: 22 63 6f 64 65 62 6c 6f 63 6b 22 3e 3c 70 72 65  "codeblock"><pre
d9b0: 3e 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c  >int (*xEof)(sql
d9c0: 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
d9d0: 2a 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 64 69 76 3e  *);.</pre></div>
d9e0: 0a 0a 3c 70 3e 54 68 65 20 78 45 6f 66 20 6d 65  ..<p>The xEof me
d9f0: 74 68 6f 64 20 6d 75 73 74 20 72 65 74 75 72 6e  thod must return
da00: 20 66 61 6c 73 65 20 28 7a 65 72 6f 29 20 69 66   false (zero) if
da10: 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63   the specified c
da20: 75 72 73 6f 72 20 0a 63 75 72 72 65 6e 74 6c 79  ursor .currently
da30: 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 76 61 6c   points to a val
da40: 69 64 20 72 6f 77 20 6f 66 20 64 61 74 61 2c 20  id row of data, 
da50: 6f 72 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  or true (non-zer
da60: 6f 29 20 6f 74 68 65 72 77 69 73 65 2e 20 0a 54  o) otherwise. .T
da70: 68 69 73 20 6d 65 74 68 6f 64 20 69 73 20 63 61  his method is ca
da80: 6c 6c 65 64 20 62 79 20 74 68 65 20 53 51 4c 20  lled by the SQL 
da90: 65 6e 67 69 6e 65 20 69 6d 6d 65 64 69 61 74 65  engine immediate
daa0: 6c 79 20 61 66 74 65 72 20 65 61 63 68 20 0a 3c  ly after each .<
dab0: 61 20 68 72 65 66 3d 22 76 74 61 62 2e 68 74 6d  a href="vtab.htm
dac0: 6c 23 78 66 69 6c 74 65 72 22 3e 78 46 69 6c 74  l#xfilter">xFilt
dad0: 65 72 3c 2f 61 3e 20 61 6e 64 20 3c 61 20 68 72  er</a> and <a hr
dae0: 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23 78 6e  ef="vtab.html#xn
daf0: 65 78 74 22 3e 78 4e 65 78 74 3c 2f 61 3e 20 69  ext">xNext</a> i
db00: 6e 76 6f 63 61 74 69 6f 6e 2e 0a 0a 3c 2f 70 3e  nvocation...</p>
db10: 3c 70 3e 54 68 65 20 78 45 6f 66 20 6d 65 74 68  <p>The xEof meth
db20: 6f 64 20 69 73 20 72 65 71 75 69 72 65 64 20 66  od is required f
db30: 6f 72 20 65 76 65 72 79 20 76 69 72 74 75 61 6c  or every virtual
db40: 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
db50: 61 74 69 6f 6e 2e 0a 0a 3c 61 20 6e 61 6d 65 3d  ation...<a name=
db60: 22 78 66 69 6c 74 65 72 22 3e 3c 2f 61 3e 0a 0a  "xfilter"></a>..
db70: 3c 2f 70 3e 3c 68 32 20 69 64 3d 22 74 68 65 5f  </p><h2 id="the_
db80: 78 66 69 6c 74 65 72 5f 6d 65 74 68 6f 64 22 3e  xfilter_method">
db90: 3c 73 70 61 6e 3e 32 2e 39 2e 20 3c 2f 73 70 61  <span>2.9. </spa
dba0: 6e 3e 54 68 65 20 78 46 69 6c 74 65 72 20 4d 65  n>The xFilter Me
dbb0: 74 68 6f 64 3c 2f 68 32 3e 0a 0a 3c 64 69 76 20  thod</h2>..<div 
dbc0: 63 6c 61 73 73 3d 22 63 6f 64 65 62 6c 6f 63 6b  class="codeblock
dbd0: 22 3e 3c 70 72 65 3e 69 6e 74 20 28 2a 78 46 69  "><pre>int (*xFi
dbe0: 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74  lter)(sqlite3_vt
dbf0: 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20  ab_cursor*, int 
dc00: 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68  idxNum, const ch
dc10: 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 20 20  ar *idxStr,.    
dc20: 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72            int ar
dc30: 67 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  gc, sqlite3_valu
dc40: 65 20 2a 2a 61 72 67 76 29 3b 0a 3c 2f 70 72 65  e **argv);.</pre
dc50: 3e 3c 2f 64 69 76 3e 0a 0a 3c 70 3e 54 68 69 73  ></div>..<p>This
dc60: 20 6d 65 74 68 6f 64 20 62 65 67 69 6e 73 20 61   method begins a
dc70: 20 73 65 61 72 63 68 20 6f 66 20 61 20 76 69 72   search of a vir
dc80: 74 75 61 6c 20 74 61 62 6c 65 2e 20 0a 54 68 65  tual table. .The
dc90: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
dca0: 69 73 20 61 20 63 75 72 73 6f 72 20 6f 70 65 6e  is a cursor open
dcb0: 65 64 20 62 79 20 3c 61 20 68 72 65 66 3d 22 76  ed by <a href="v
dcc0: 74 61 62 2e 68 74 6d 6c 23 78 6f 70 65 6e 22 3e  tab.html#xopen">
dcd0: 78 4f 70 65 6e 3c 2f 61 3e 2e 20 0a 54 68 65 20  xOpen</a>. .The 
dce0: 6e 65 78 74 20 74 77 6f 20 61 72 67 75 6d 65 6e  next two argumen
dcf0: 74 73 20 64 65 66 69 6e 65 20 61 20 70 61 72 74  ts define a part
dd00: 69 63 75 6c 61 72 20 73 65 61 72 63 68 20 69 6e  icular search in
dd10: 64 65 78 20 70 72 65 76 69 6f 75 73 6c 79 20 0a  dex previously .
dd20: 63 68 6f 73 65 6e 20 62 79 20 3c 61 20 68 72 65  chosen by <a hre
dd30: 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23 78 62 65  f="vtab.html#xbe
dd40: 73 74 69 6e 64 65 78 22 3e 78 42 65 73 74 49 6e  stindex">xBestIn
dd50: 64 65 78 3c 2f 61 3e 2e 20 54 68 65 20 73 70 65  dex</a>. The spe
dd60: 63 69 66 69 63 20 6d 65 61 6e 69 6e 67 73 20 6f  cific meanings o
dd70: 66 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78  f idxNum and idx
dd80: 53 74 72 20 0a 61 72 65 20 75 6e 69 6d 70 6f 72  Str .are unimpor
dd90: 74 61 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  tant as long as 
dda0: 78 46 69 6c 74 65 72 20 61 6e 64 20 78 42 65 73  xFilter and xBes
ddb0: 74 49 6e 64 65 78 20 61 67 72 65 65 20 6f 6e 20  tIndex agree on 
ddc0: 77 68 61 74 20 0a 74 68 61 74 20 6d 65 61 6e 69  what .that meani
ddd0: 6e 67 20 69 73 2e 0a 0a 3c 2f 70 3e 3c 70 3e 54  ng is...</p><p>T
dde0: 68 65 20 78 42 65 73 74 49 6e 64 65 78 20 66 75  he xBestIndex fu
ddf0: 6e 63 74 69 6f 6e 20 6d 61 79 20 68 61 76 65 20  nction may have 
de00: 72 65 71 75 65 73 74 65 64 20 74 68 65 20 76 61  requested the va
de10: 6c 75 65 73 20 6f 66 20 0a 63 65 72 74 61 69 6e  lues of .certain
de20: 20 65 78 70 72 65 73 73 69 6f 6e 73 20 75 73 69   expressions usi
de30: 6e 67 20 74 68 65 20 61 43 6f 6e 73 74 72 61 69  ng the aConstrai
de40: 6e 74 55 73 61 67 65 5b 5d 2e 61 72 67 76 49 6e  ntUsage[].argvIn
de50: 64 65 78 20 76 61 6c 75 65 73 20 0a 6f 66 20 74  dex values .of t
de60: 68 65 20 3c 61 20 68 72 65 66 3d 22 63 33 72 65  he <a href="c3re
de70: 66 2f 69 6e 64 65 78 5f 69 6e 66 6f 2e 68 74 6d  f/index_info.htm
de80: 6c 22 3e 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  l">sqlite3_index
de90: 5f 69 6e 66 6f 3c 2f 61 3e 20 73 74 72 75 63 74  _info</a> struct
dea0: 75 72 65 2e 20 0a 54 68 6f 73 65 20 76 61 6c 75  ure. .Those valu
deb0: 65 73 20 61 72 65 20 70 61 73 73 65 64 20 74 6f  es are passed to
dec0: 20 78 46 69 6c 74 65 72 20 75 73 69 6e 67 20 74   xFilter using t
ded0: 68 65 20 61 72 67 63 20 61 6e 64 20 61 72 67 76  he argc and argv
dee0: 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 0a 3c 2f   parameters...</
def0: 70 3e 3c 70 3e 49 66 20 74 68 65 20 76 69 72 74  p><p>If the virt
df00: 75 61 6c 20 74 61 62 6c 65 20 63 6f 6e 74 61 69  ual table contai
df10: 6e 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 72  ns one or more r
df20: 6f 77 73 20 74 68 61 74 20 6d 61 74 63 68 20 74  ows that match t
df30: 68 65 0a 73 65 61 72 63 68 20 63 72 69 74 65 72  he.search criter
df40: 69 61 2c 20 74 68 65 6e 20 74 68 65 20 63 75 72  ia, then the cur
df50: 73 6f 72 20 6d 75 73 74 20 62 65 20 6c 65 66 74  sor must be left
df60: 20 70 6f 69 6e 74 20 61 74 20 74 68 65 20 66 69   point at the fi
df70: 72 73 74 20 72 6f 77 2e 0a 53 75 62 73 65 71 75  rst row..Subsequ
df80: 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 3c 61 20  ent calls to <a 
df90: 68 72 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23  href="vtab.html#
dfa0: 78 65 6f 66 22 3e 78 45 6f 66 3c 2f 61 3e 20 6d  xeof">xEof</a> m
dfb0: 75 73 74 20 72 65 74 75 72 6e 20 66 61 6c 73 65  ust return false
dfc0: 20 28 7a 65 72 6f 29 2e 0a 49 66 20 74 68 65 72   (zero)..If ther
dfd0: 65 20 61 72 65 20 6e 6f 20 72 6f 77 73 20 6d 61  e are no rows ma
dfe0: 74 63 68 2c 20 74 68 65 6e 20 74 68 65 20 63 75  tch, then the cu
dff0: 72 73 6f 72 20 6d 75 73 74 20 62 65 20 6c 65 66  rsor must be lef
e000: 74 20 69 6e 20 61 20 73 74 61 74 65 20 0a 74 68  t in a state .th
e010: 61 74 20 77 69 6c 6c 20 63 61 75 73 65 20 74 68  at will cause th
e020: 65 20 3c 61 20 68 72 65 66 3d 22 76 74 61 62 2e  e <a href="vtab.
e030: 68 74 6d 6c 23 78 65 6f 66 22 3e 78 45 6f 66 3c  html#xeof">xEof<
e040: 2f 61 3e 20 74 6f 20 72 65 74 75 72 6e 20 74 72  /a> to return tr
e050: 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 2e 0a 54  ue (non-zero)..T
e060: 68 65 20 53 51 4c 69 74 65 20 65 6e 67 69 6e 65  he SQLite engine
e070: 20 77 69 6c 6c 20 75 73 65 0a 74 68 65 20 3c 61   will use.the <a
e080: 20 68 72 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c   href="vtab.html
e090: 23 78 63 6f 6c 75 6d 6e 22 3e 78 43 6f 6c 75 6d  #xcolumn">xColum
e0a0: 6e 3c 2f 61 3e 20 61 6e 64 20 3c 61 20 68 72 65  n</a> and <a hre
e0b0: 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23 78 72 6f  f="vtab.html#xro
e0c0: 77 69 64 22 3e 78 52 6f 77 69 64 3c 2f 61 3e 20  wid">xRowid</a> 
e0d0: 6d 65 74 68 6f 64 73 20 74 6f 20 61 63 63 65 73  methods to acces
e0e0: 73 20 74 68 61 74 20 72 6f 77 20 63 6f 6e 74 65  s that row conte
e0f0: 6e 74 2e 0a 54 68 65 20 3c 61 20 68 72 65 66 3d  nt..The <a href=
e100: 22 76 74 61 62 2e 68 74 6d 6c 23 78 6e 65 78 74  "vtab.html#xnext
e110: 22 3e 78 4e 65 78 74 3c 2f 61 3e 20 6d 65 74 68  ">xNext</a> meth
e120: 6f 64 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20  od will be used 
e130: 74 6f 20 61 64 76 61 6e 63 65 20 74 6f 20 74 68  to advance to th
e140: 65 20 6e 65 78 74 20 72 6f 77 2e 0a 0a 3c 2f 70  e next row...</p
e150: 3e 3c 70 3e 54 68 69 73 20 6d 65 74 68 6f 64 20  ><p>This method 
e160: 6d 75 73 74 20 72 65 74 75 72 6e 20 3c 61 20 68  must return <a h
e170: 72 65 66 3d 22 72 65 73 63 6f 64 65 2e 68 74 6d  ref="rescode.htm
e180: 6c 23 6f 6b 22 3e 53 51 4c 49 54 45 5f 4f 4b 3c  l#ok">SQLITE_OK<
e190: 2f 61 3e 20 69 66 20 73 75 63 63 65 73 73 66 75  /a> if successfu
e1a0: 6c 2c 20 6f 72 20 61 6e 20 73 71 6c 69 74 65 20  l, or an sqlite 
e1b0: 0a 3c 61 20 68 72 65 66 3d 22 72 65 73 63 6f 64  .<a href="rescod
e1c0: 65 2e 68 74 6d 6c 22 3e 65 72 72 6f 72 20 63 6f  e.html">error co
e1d0: 64 65 3c 2f 61 3e 20 69 66 20 61 6e 20 65 72 72  de</a> if an err
e1e0: 6f 72 20 6f 63 63 75 72 73 2e 0a 0a 3c 2f 70 3e  or occurs...</p>
e1f0: 3c 70 3e 54 68 65 20 78 46 69 6c 74 65 72 20 6d  <p>The xFilter m
e200: 65 74 68 6f 64 20 69 73 20 72 65 71 75 69 72 65  ethod is require
e210: 64 20 66 6f 72 20 65 76 65 72 79 20 76 69 72 74  d for every virt
e220: 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
e230: 65 6e 74 61 74 69 6f 6e 2e 0a 0a 3c 61 20 6e 61  entation...<a na
e240: 6d 65 3d 22 78 6e 65 78 74 22 3e 3c 2f 61 3e 0a  me="xnext"></a>.
e250: 0a 3c 2f 70 3e 3c 68 32 20 69 64 3d 22 74 68 65  .</p><h2 id="the
e260: 5f 78 6e 65 78 74 5f 6d 65 74 68 6f 64 22 3e 3c  _xnext_method"><
e270: 73 70 61 6e 3e 32 2e 31 30 2e 20 3c 2f 73 70 61  span>2.10. </spa
e280: 6e 3e 54 68 65 20 78 4e 65 78 74 20 4d 65 74 68  n>The xNext Meth
e290: 6f 64 3c 2f 68 32 3e 0a 0a 3c 64 69 76 20 63 6c  od</h2>..<div cl
e2a0: 61 73 73 3d 22 63 6f 64 65 62 6c 6f 63 6b 22 3e  ass="codeblock">
e2b0: 3c 70 72 65 3e 69 6e 74 20 28 2a 78 4e 65 78 74  <pre>int (*xNext
e2c0: 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
e2d0: 75 72 73 6f 72 2a 29 3b 0a 3c 2f 70 72 65 3e 3c  ursor*);.</pre><
e2e0: 2f 64 69 76 3e 0a 0a 3c 70 3e 54 68 65 20 78 4e  /div>..<p>The xN
e2f0: 65 78 74 20 6d 65 74 68 6f 64 20 61 64 76 61 6e  ext method advan
e300: 63 65 73 20 61 20 3c 61 20 68 72 65 66 3d 22 63  ces a <a href="c
e310: 33 72 65 66 2f 76 74 61 62 5f 63 75 72 73 6f 72  3ref/vtab_cursor
e320: 2e 68 74 6d 6c 22 3e 76 69 72 74 75 61 6c 20 74  .html">virtual t
e330: 61 62 6c 65 20 63 75 72 73 6f 72 3c 2f 61 3e 0a  able cursor</a>.
e340: 74 6f 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20  to the next row 
e350: 6f 66 20 61 20 72 65 73 75 6c 74 20 73 65 74 20  of a result set 
e360: 69 6e 69 74 69 61 74 65 64 20 62 79 20 3c 61 20  initiated by <a 
e370: 68 72 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23  href="vtab.html#
e380: 78 66 69 6c 74 65 72 22 3e 78 46 69 6c 74 65 72  xfilter">xFilter
e390: 3c 2f 61 3e 2e 20 0a 49 66 20 74 68 65 20 63 75  </a>. .If the cu
e3a0: 72 73 6f 72 20 69 73 20 61 6c 72 65 61 64 79 20  rsor is already 
e3b0: 70 6f 69 6e 74 69 6e 67 20 61 74 20 74 68 65 20  pointing at the 
e3c0: 6c 61 73 74 20 72 6f 77 20 77 68 65 6e 20 74 68  last row when th
e3d0: 69 73 20 0a 72 6f 75 74 69 6e 65 20 69 73 20 63  is .routine is c
e3e0: 61 6c 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  alled, then the 
e3f0: 63 75 72 73 6f 72 20 6e 6f 20 6c 6f 6e 67 65 72  cursor no longer
e400: 20 70 6f 69 6e 74 73 20 74 6f 20 76 61 6c 69 64   points to valid
e410: 20 0a 64 61 74 61 20 61 6e 64 20 61 20 73 75 62   .data and a sub
e420: 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
e430: 74 68 65 20 3c 61 20 68 72 65 66 3d 22 76 74 61  the <a href="vta
e440: 62 2e 68 74 6d 6c 23 78 65 6f 66 22 3e 78 45 6f  b.html#xeof">xEo
e450: 66 3c 2f 61 3e 20 6d 65 74 68 6f 64 20 6d 75 73  f</a> method mus
e460: 74 20 72 65 74 75 72 6e 20 74 72 75 65 20 28 6e  t return true (n
e470: 6f 6e 2d 7a 65 72 6f 29 2e 20 0a 49 66 20 74 68  on-zero). .If th
e480: 65 20 63 75 72 73 6f 72 20 69 73 20 73 75 63 63  e cursor is succ
e490: 65 73 73 66 75 6c 6c 79 20 61 64 76 61 6e 63 65  essfully advance
e4a0: 64 20 74 6f 20 61 6e 6f 74 68 65 72 20 72 6f 77  d to another row
e4b0: 20 6f 66 20 63 6f 6e 74 65 6e 74 2c 20 74 68 65   of content, the
e4c0: 6e 0a 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n.subsequent cal
e4d0: 6c 73 20 74 6f 20 3c 61 20 68 72 65 66 3d 22 76  ls to <a href="v
e4e0: 74 61 62 2e 68 74 6d 6c 23 78 65 6f 66 22 3e 78  tab.html#xeof">x
e4f0: 45 6f 66 3c 2f 61 3e 20 6d 75 73 74 20 72 65 74  Eof</a> must ret
e500: 75 72 6e 20 66 61 6c 73 65 20 28 7a 65 72 6f 29  urn false (zero)
e510: 2e 0a 0a 3c 2f 70 3e 3c 70 3e 54 68 69 73 20 6d  ...</p><p>This m
e520: 65 74 68 6f 64 20 6d 75 73 74 20 72 65 74 75 72  ethod must retur
e530: 6e 20 3c 61 20 68 72 65 66 3d 22 72 65 73 63 6f  n <a href="resco
e540: 64 65 2e 68 74 6d 6c 23 6f 6b 22 3e 53 51 4c 49  de.html#ok">SQLI
e550: 54 45 5f 4f 4b 3c 2f 61 3e 20 69 66 20 73 75 63  TE_OK</a> if suc
e560: 63 65 73 73 66 75 6c 2c 20 6f 72 20 61 6e 20 73  cessful, or an s
e570: 71 6c 69 74 65 20 0a 3c 61 20 68 72 65 66 3d 22  qlite .<a href="
e580: 72 65 73 63 6f 64 65 2e 68 74 6d 6c 22 3e 65 72  rescode.html">er
e590: 72 6f 72 20 63 6f 64 65 3c 2f 61 3e 20 69 66 20  ror code</a> if 
e5a0: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
e5b0: 0a 0a 3c 2f 70 3e 3c 70 3e 54 68 65 20 78 4e 65  ..</p><p>The xNe
e5c0: 78 74 20 6d 65 74 68 6f 64 20 69 73 20 72 65 71  xt method is req
e5d0: 75 69 72 65 64 20 66 6f 72 20 65 76 65 72 79 20  uired for every 
e5e0: 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  virtual table im
e5f0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 0a 3c  plementation...<
e600: 61 20 6e 61 6d 65 3d 22 78 63 6f 6c 75 6d 6e 22  a name="xcolumn"
e610: 3e 3c 2f 61 3e 0a 0a 3c 2f 70 3e 3c 68 32 20 69  ></a>..</p><h2 i
e620: 64 3d 22 74 68 65 5f 78 63 6f 6c 75 6d 6e 5f 6d  d="the_xcolumn_m
e630: 65 74 68 6f 64 22 3e 3c 73 70 61 6e 3e 32 2e 31  ethod"><span>2.1
e640: 31 2e 20 3c 2f 73 70 61 6e 3e 54 68 65 20 78 43  1. </span>The xC
e650: 6f 6c 75 6d 6e 20 4d 65 74 68 6f 64 3c 2f 68 32  olumn Method</h2
e660: 3e 0a 0a 3c 64 69 76 20 63 6c 61 73 73 3d 22 63  >..<div class="c
e670: 6f 64 65 62 6c 6f 63 6b 22 3e 3c 70 72 65 3e 69  odeblock"><pre>i
e680: 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71  nt (*xColumn)(sq
e690: 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
e6a0: 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r*, sqlite3_cont
e6b0: 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 3c 2f  ext*, int N);.</
e6c0: 70 72 65 3e 3c 2f 64 69 76 3e 0a 0a 3c 70 3e 54  pre></div>..<p>T
e6d0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 69  he SQLite core i
e6e0: 6e 76 6f 6b 65 73 20 74 68 69 73 20 6d 65 74 68  nvokes this meth
e6f0: 6f 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  od in order to f
e700: 69 6e 64 20 74 68 65 20 76 61 6c 75 65 20 66 6f  ind the value fo
e710: 72 20 0a 74 68 65 20 4e 2d 74 68 20 63 6f 6c 75  r .the N-th colu
e720: 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
e730: 74 20 72 6f 77 2e 20 4e 20 69 73 20 7a 65 72 6f  t row. N is zero
e740: 2d 62 61 73 65 64 20 73 6f 20 74 68 65 20 66 69  -based so the fi
e750: 72 73 74 20 63 6f 6c 75 6d 6e 20 0a 69 73 20 6e  rst column .is n
e760: 75 6d 62 65 72 65 64 20 30 2e 20 0a 54 68 65 20  umbered 0. .The 
e770: 78 43 6f 6c 75 6d 6e 20 6d 65 74 68 6f 64 20 6d  xColumn method m
e780: 61 79 20 72 65 74 75 72 6e 20 69 74 73 20 72 65  ay return its re
e790: 73 75 6c 74 20 62 61 63 6b 20 74 6f 20 53 51 4c  sult back to SQL
e7a0: 69 74 65 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ite using one of
e7b0: 20 74 68 65 0a 66 6f 6c 6c 6f 77 69 6e 67 20 69   the.following i
e7c0: 6e 74 65 72 66 61 63 65 3a 0a 0a 3c 2f 70 3e 3c  nterface:..</p><
e7d0: 70 3e 0a 3c 2f 70 3e 3c 75 6c 3e 0a 3c 6c 69 3e  p>.</p><ul>.<li>
e7e0: 20 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f   <a href="c3ref/
e7f0: 72 65 73 75 6c 74 5f 62 6c 6f 62 2e 68 74 6d 6c  result_blob.html
e800: 22 3e 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  ">sqlite3_result
e810: 5f 62 6c 6f 62 28 29 3c 2f 61 3e 0a 3c 2f 6c 69  _blob()</a>.</li
e820: 3e 3c 6c 69 3e 20 3c 61 20 68 72 65 66 3d 22 63  ><li> <a href="c
e830: 33 72 65 66 2f 72 65 73 75 6c 74 5f 62 6c 6f 62  3ref/result_blob
e840: 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 72  .html">sqlite3_r
e850: 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 3c 2f  esult_double()</
e860: 61 3e 0a 3c 2f 6c 69 3e 3c 6c 69 3e 20 3c 61 20  a>.</li><li> <a 
e870: 68 72 65 66 3d 22 63 33 72 65 66 2f 72 65 73 75  href="c3ref/resu
e880: 6c 74 5f 62 6c 6f 62 2e 68 74 6d 6c 22 3e 73 71  lt_blob.html">sq
e890: 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
e8a0: 28 29 3c 2f 61 3e 0a 3c 2f 6c 69 3e 3c 6c 69 3e  ()</a>.</li><li>
e8b0: 20 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f   <a href="c3ref/
e8c0: 72 65 73 75 6c 74 5f 62 6c 6f 62 2e 68 74 6d 6c  result_blob.html
e8d0: 22 3e 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  ">sqlite3_result
e8e0: 5f 69 6e 74 36 34 28 29 3c 2f 61 3e 0a 3c 2f 6c  _int64()</a>.</l
e8f0: 69 3e 3c 6c 69 3e 20 3c 61 20 68 72 65 66 3d 22  i><li> <a href="
e900: 63 33 72 65 66 2f 72 65 73 75 6c 74 5f 62 6c 6f  c3ref/result_blo
e910: 62 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f  b.html">sqlite3_
e920: 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 3c 2f 61  result_null()</a
e930: 3e 0a 3c 2f 6c 69 3e 3c 6c 69 3e 20 3c 61 20 68  >.</li><li> <a h
e940: 72 65 66 3d 22 63 33 72 65 66 2f 72 65 73 75 6c  ref="c3ref/resul
e950: 74 5f 62 6c 6f 62 2e 68 74 6d 6c 22 3e 73 71 6c  t_blob.html">sql
e960: 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
e970: 28 29 3c 2f 61 3e 0a 3c 2f 6c 69 3e 3c 6c 69 3e  ()</a>.</li><li>
e980: 20 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f   <a href="c3ref/
e990: 72 65 73 75 6c 74 5f 62 6c 6f 62 2e 68 74 6d 6c  result_blob.html
e9a0: 22 3e 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  ">sqlite3_result
e9b0: 5f 74 65 78 74 31 36 28 29 3c 2f 61 3e 0a 3c 2f  _text16()</a>.</
e9c0: 6c 69 3e 3c 6c 69 3e 20 3c 61 20 68 72 65 66 3d  li><li> <a href=
e9d0: 22 63 33 72 65 66 2f 72 65 73 75 6c 74 5f 62 6c  "c3ref/result_bl
e9e0: 6f 62 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33  ob.html">sqlite3
e9f0: 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
ea00: 28 29 3c 2f 61 3e 0a 3c 2f 6c 69 3e 3c 6c 69 3e  ()</a>.</li><li>
ea10: 20 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f   <a href="c3ref/
ea20: 72 65 73 75 6c 74 5f 62 6c 6f 62 2e 68 74 6d 6c  result_blob.html
ea30: 22 3e 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  ">sqlite3_result
ea40: 5f 74 65 78 74 31 36 62 65 28 29 3c 2f 61 3e 0a  _text16be()</a>.
ea50: 3c 2f 6c 69 3e 3c 6c 69 3e 20 3c 61 20 68 72 65  </li><li> <a hre
ea60: 66 3d 22 63 33 72 65 66 2f 72 65 73 75 6c 74 5f  f="c3ref/result_
ea70: 62 6c 6f 62 2e 68 74 6d 6c 22 3e 73 71 6c 69 74  blob.html">sqlit
ea80: 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
ea90: 6f 62 28 29 3c 2f 61 3e 0a 3c 2f 6c 69 3e 3c 2f  ob()</a>.</li></
eaa0: 75 6c 3e 0a 0a 0a 3c 70 3e 49 66 20 74 68 65 20  ul>...<p>If the 
eab0: 78 43 6f 6c 75 6d 6e 20 6d 65 74 68 6f 64 20 69  xColumn method i
eac0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61  mplementation ca
ead0: 6c 6c 73 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20  lls none of the 
eae0: 66 75 6e 63 74 69 6f 6e 73 20 61 62 6f 76 65 2c  functions above,
eaf0: 0a 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20  .then the value 
eb00: 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 64 65  of the column de
eb10: 66 61 75 6c 74 73 20 74 6f 20 61 6e 20 53 51 4c  faults to an SQL
eb20: 20 4e 55 4c 4c 2e 0a 0a 3c 2f 70 3e 3c 70 3e 54   NULL...</p><p>T
eb30: 6f 20 72 61 69 73 65 20 61 6e 20 65 72 72 6f 72  o raise an error
eb40: 2c 20 74 68 65 20 78 43 6f 6c 75 6d 6e 20 6d 65  , the xColumn me
eb50: 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20  thod should use 
eb60: 6f 6e 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  one of the resul
eb70: 74 5f 74 65 78 74 28 29 20 0a 6d 65 74 68 6f 64  t_text() .method
eb80: 73 20 74 6f 20 73 65 74 20 74 68 65 20 65 72 72  s to set the err
eb90: 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 2c  or message text,
eba0: 20 74 68 65 6e 20 72 65 74 75 72 6e 20 61 6e 20   then return an 
ebb0: 61 70 70 72 6f 70 72 69 61 74 65 0a 3c 61 20 68  appropriate.<a h
ebc0: 72 65 66 3d 22 72 65 73 63 6f 64 65 2e 68 74 6d  ref="rescode.htm
ebd0: 6c 22 3e 65 72 72 6f 72 20 63 6f 64 65 3c 2f 61  l">error code</a
ebe0: 3e 2e 20 20 54 68 65 20 78 43 6f 6c 75 6d 6e 20  >.  The xColumn 
ebf0: 6d 65 74 68 6f 64 20 6d 75 73 74 20 72 65 74 75  method must retu
ec00: 72 6e 20 3c 61 20 68 72 65 66 3d 22 72 65 73 63  rn <a href="resc
ec10: 6f 64 65 2e 68 74 6d 6c 23 6f 6b 22 3e 53 51 4c  ode.html#ok">SQL
ec20: 49 54 45 5f 4f 4b 3c 2f 61 3e 20 6f 6e 20 73 75  ITE_OK</a> on su
ec30: 63 63 65 73 73 2e 0a 0a 3c 2f 70 3e 3c 70 3e 54  ccess...</p><p>T
ec40: 68 65 20 78 43 6f 6c 75 6d 6e 20 6d 65 74 68 6f  he xColumn metho
ec50: 64 20 69 73 20 72 65 71 75 69 72 65 64 20 66 6f  d is required fo
ec60: 72 20 65 76 65 72 79 20 76 69 72 74 75 61 6c 20  r every virtual 
ec70: 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
ec80: 74 69 6f 6e 2e 0a 0a 3c 61 20 6e 61 6d 65 3d 22  tion...<a name="
ec90: 78 72 6f 77 69 64 22 3e 3c 2f 61 3e 0a 0a 3c 2f  xrowid"></a>..</
eca0: 70 3e 3c 68 32 20 69 64 3d 22 74 68 65 5f 78 72  p><h2 id="the_xr
ecb0: 6f 77 69 64 5f 6d 65 74 68 6f 64 22 3e 3c 73 70  owid_method"><sp
ecc0: 61 6e 3e 32 2e 31 32 2e 20 3c 2f 73 70 61 6e 3e  an>2.12. </span>
ecd0: 54 68 65 20 78 52 6f 77 69 64 20 4d 65 74 68 6f  The xRowid Metho
ece0: 64 3c 2f 68 32 3e 0a 0a 3c 64 69 76 20 63 6c 61  d</h2>..<div cla
ecf0: 73 73 3d 22 63 6f 64 65 62 6c 6f 63 6b 22 3e 3c  ss="codeblock"><
ed00: 70 72 65 3e 69 6e 74 20 28 2a 78 52 6f 77 69 64  pre>int (*xRowid
ed10: 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
ed20: 75 72 73 6f 72 20 2a 70 43 75 72 2c 20 73 71 6c  ursor *pCur, sql
ed30: 69 74 65 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69  ite_int64 *pRowi
ed40: 64 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 64 69 76 3e  d);.</pre></div>
ed50: 0a 0a 3c 70 3e 41 20 73 75 63 63 65 73 73 66 75  ..<p>A successfu
ed60: 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  l invocation of 
ed70: 74 68 69 73 20 6d 65 74 68 6f 64 20 77 69 6c 6c  this method will
ed80: 20 63 61 75 73 65 20 2a 70 52 6f 77 69 64 20 74   cause *pRowid t
ed90: 6f 20 62 65 0a 66 69 6c 6c 65 64 20 77 69 74 68  o be.filled with
eda0: 20 74 68 65 20 3c 61 20 68 72 65 66 3d 22 6c 61   the <a href="la
edb0: 6e 67 5f 63 72 65 61 74 65 74 61 62 6c 65 2e 68  ng_createtable.h
edc0: 74 6d 6c 23 72 6f 77 69 64 22 3e 72 6f 77 69 64  tml#rowid">rowid
edd0: 3c 2f 61 3e 20 6f 66 20 72 6f 77 20 74 68 61 74  </a> of row that
ede0: 20 74 68 65 0a 3c 61 20 68 72 65 66 3d 22 63 33   the.<a href="c3
edf0: 72 65 66 2f 76 74 61 62 5f 63 75 72 73 6f 72 2e  ref/vtab_cursor.
ee00: 68 74 6d 6c 22 3e 76 69 72 74 75 61 6c 20 74 61  html">virtual ta
ee10: 62 6c 65 20 63 75 72 73 6f 72 3c 2f 61 3e 20 70  ble cursor</a> p
ee20: 43 75 72 20 69 73 20 63 75 72 72 65 6e 74 6c 79  Cur is currently
ee30: 20 70 6f 69 6e 74 69 6e 67 20 61 74 2e 0a 54 68   pointing at..Th
ee40: 69 73 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  is method return
ee50: 73 20 3c 61 20 68 72 65 66 3d 22 72 65 73 63 6f  s <a href="resco
ee60: 64 65 2e 68 74 6d 6c 23 6f 6b 22 3e 53 51 4c 49  de.html#ok">SQLI
ee70: 54 45 5f 4f 4b 3c 2f 61 3e 20 6f 6e 20 73 75 63  TE_OK</a> on suc
ee80: 63 65 73 73 2e 0a 49 74 20 72 65 74 75 72 6e 73  cess..It returns
ee90: 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
eea0: 3c 61 20 68 72 65 66 3d 22 72 65 73 63 6f 64 65  <a href="rescode
eeb0: 2e 68 74 6d 6c 22 3e 65 72 72 6f 72 20 63 6f 64  .html">error cod
eec0: 65 3c 2f 61 3e 20 6f 6e 20 66 61 69 6c 75 72 65  e</a> on failure
eed0: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 78 52  .</p>..<p>The xR
eee0: 6f 77 69 64 20 6d 65 74 68 6f 64 20 69 73 20 72  owid method is r
eef0: 65 71 75 69 72 65 64 20 66 6f 72 20 65 76 65 72  equired for ever
ef00: 79 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  y virtual table 
ef10: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a  implementation..
ef20: 0a 3c 61 20 6e 61 6d 65 3d 22 78 75 70 64 61 74  .<a name="xupdat
ef30: 65 22 3e 3c 2f 61 3e 0a 0a 3c 2f 70 3e 3c 68 32  e"></a>..</p><h2
ef40: 20 69 64 3d 22 74 68 65 5f 78 75 70 64 61 74 65   id="the_xupdate
ef50: 5f 6d 65 74 68 6f 64 22 3e 3c 73 70 61 6e 3e 32  _method"><span>2
ef60: 2e 31 33 2e 20 3c 2f 73 70 61 6e 3e 54 68 65 20  .13. </span>The 
ef70: 78 55 70 64 61 74 65 20 4d 65 74 68 6f 64 3c 2f  xUpdate Method</
ef80: 68 32 3e 0a 0a 3c 64 69 76 20 63 6c 61 73 73 3d  h2>..<div class=
ef90: 22 63 6f 64 65 62 6c 6f 63 6b 22 3e 3c 70 72 65  "codeblock"><pre
efa0: 3e 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28  >int (*xUpdate)(
efb0: 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20  .  sqlite3_vtab 
efc0: 2a 70 56 54 61 62 2c 0a 20 20 69 6e 74 20 61 72  *pVTab,.  int ar
efd0: 67 63 2c 0a 20 20 73 71 6c 69 74 65 33 5f 76 61  gc,.  sqlite3_va
efe0: 6c 75 65 20 2a 2a 61 72 67 76 2c 0a 20 20 73 71  lue **argv,.  sq
eff0: 6c 69 74 65 5f 69 6e 74 36 34 20 2a 70 52 6f 77  lite_int64 *pRow
f000: 69 64 0a 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 64 69  id.);.</pre></di
f010: 76 3e 0a 0a 3c 70 3e 41 6c 6c 20 63 68 61 6e 67  v>..<p>All chang
f020: 65 73 20 74 6f 20 61 20 76 69 72 74 75 61 6c 20  es to a virtual 
f030: 74 61 62 6c 65 20 61 72 65 20 6d 61 64 65 20 75  table are made u
f040: 73 69 6e 67 20 74 68 65 20 78 55 70 64 61 74 65  sing the xUpdate
f050: 20 6d 65 74 68 6f 64 2e 0a 54 68 69 73 20 6f 6e   method..This on
f060: 65 20 6d 65 74 68 6f 64 20 63 61 6e 20 62 65 20  e method can be 
f070: 75 73 65 64 20 74 6f 20 69 6e 73 65 72 74 2c 20  used to insert, 
f080: 64 65 6c 65 74 65 2c 20 6f 72 20 75 70 64 61 74  delete, or updat
f090: 65 2e 0a 0a 3c 2f 70 3e 3c 70 3e 54 68 65 20 61  e...</p><p>The a
f0a0: 72 67 63 20 70 61 72 61 6d 65 74 65 72 20 73 70  rgc parameter sp
f0b0: 65 63 69 66 69 65 73 20 74 68 65 20 6e 75 6d 62  ecifies the numb
f0c0: 65 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69 6e  er of entries in
f0d0: 20 74 68 65 20 61 72 67 76 20 61 72 72 61 79 2e   the argv array.
f0e0: 20 0a 54 68 65 20 76 61 6c 75 65 20 6f 66 20 61   .The value of a
f0f0: 72 67 63 20 77 69 6c 6c 20 62 65 20 31 20 66 6f  rgc will be 1 fo
f100: 72 20 61 20 70 75 72 65 20 64 65 6c 65 74 65 20  r a pure delete 
f110: 6f 70 65 72 61 74 69 6f 6e 20 6f 72 20 4e 2b 32  operation or N+2
f120: 20 66 6f 72 20 61 6e 20 69 6e 73 65 72 74 0a 6f   for an insert.o
f130: 72 20 72 65 70 6c 61 63 65 20 6f 72 20 75 70 64  r replace or upd
f140: 61 74 65 20 77 68 65 72 65 20 4e 20 69 73 20 74  ate where N is t
f150: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
f160: 75 6d 6e 73 20 69 6e 20 74 68 65 20 74 61 62 6c  umns in the tabl
f170: 65 2e 20 20 0a 49 6e 20 74 68 65 20 70 72 65 76  e.  .In the prev
f180: 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 20 4e  ious sentence, N
f190: 20 69 6e 63 6c 75 64 65 73 20 61 6e 79 20 68 69   includes any hi
f1a0: 64 64 65 6e 20 63 6f 6c 75 6d 6e 73 2e 0a 0a 3c  dden columns...<
f1b0: 2f 70 3e 3c 70 3e 45 76 65 72 79 20 61 72 67 76  /p><p>Every argv
f1c0: 20 65 6e 74 72 79 20 77 69 6c 6c 20 68 61 76 65   entry will have
f1d0: 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 76 61 6c 75   a non-NULL valu
f1e0: 65 20 69 6e 20 43 20 62 75 74 20 6d 61 79 20 63  e in C but may c
f1f0: 6f 6e 74 61 69 6e 20 74 68 65 20 0a 53 51 4c 20  ontain the .SQL 
f200: 76 61 6c 75 65 20 4e 55 4c 4c 2e 20 20 49 6e 20  value NULL.  In 
f210: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
f220: 69 73 20 61 6c 77 61 79 73 20 74 72 75 65 20 74  is always true t
f230: 68 61 74 0a 3c 74 74 3e 61 72 67 76 26 23 39 31  hat.<tt>argv&#91
f240: 3b 69 26 23 39 33 3b 21 3d 30 3c 2f 74 74 3e 20  ;i&#93;!=0</tt> 
f250: 66 6f 72 20 3c 62 3e 69 3c 2f 62 3e 20 62 65 74  for <b>i</b> bet
f260: 77 65 65 6e 20 30 20 61 6e 64 20 3c 74 74 3e 61  ween 0 and <tt>a
f270: 72 67 63 2d 31 3c 2f 74 74 3e 2e 0a 48 6f 77 65  rgc-1</tt>..Howe
f280: 76 65 72 2c 20 69 74 20 6d 69 67 68 74 20 62 65  ver, it might be
f290: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 0a 3c   the case that.<
f2a0: 74 74 3e 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  tt>sqlite3_value
f2b0: 5f 74 79 70 65 28 61 72 67 76 26 23 39 31 3b 69  _type(argv&#91;i
f2c0: 26 23 39 33 3b 29 3d 3d 53 51 4c 49 54 45 5f 4e  &#93;)==SQLITE_N
f2d0: 55 4c 4c 3c 2f 74 74 3e 2e 0a 0a 3c 2f 70 3e 3c  ULL</tt>...</p><
f2e0: 70 3e 54 68 65 20 61 72 67 76 5b 30 5d 20 70 61  p>The argv[0] pa
f2f0: 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 3c  rameter is the <
f300: 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f 63 72 65  a href="lang_cre
f310: 61 74 65 74 61 62 6c 65 2e 68 74 6d 6c 23 72 6f  atetable.html#ro
f320: 77 69 64 22 3e 72 6f 77 69 64 3c 2f 61 3e 20 6f  wid">rowid</a> o
f330: 66 20 61 20 72 6f 77 20 69 6e 20 74 68 65 20 76  f a row in the v
f340: 69 72 74 75 61 6c 20 74 61 62 6c 65 20 0a 74 6f  irtual table .to
f350: 20 62 65 20 64 65 6c 65 74 65 64 2e 20 49 66 20   be deleted. If 
f360: 61 72 67 76 5b 30 5d 20 69 73 20 61 6e 20 53 51  argv[0] is an SQ
f370: 4c 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20  L NULL, then no 
f380: 64 65 6c 65 74 69 6f 6e 20 6f 63 63 75 72 73 2e  deletion occurs.
f390: 0a 0a 3c 2f 70 3e 3c 70 3e 54 68 65 20 61 72 67  ..</p><p>The arg
f3a0: 76 5b 31 5d 20 70 61 72 61 6d 65 74 65 72 20 69  v[1] parameter i
f3b0: 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 61  s the rowid of a
f3c0: 20 6e 65 77 20 72 6f 77 20 74 6f 20 62 65 20 69   new row to be i
f3d0: 6e 73 65 72 74 65 64 20 0a 69 6e 74 6f 20 74 68  nserted .into th
f3e0: 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e  e virtual table.
f3f0: 20 49 66 20 61 72 67 76 5b 31 5d 20 69 73 20 61   If argv[1] is a
f400: 6e 20 53 51 4c 20 4e 55 4c 4c 2c 20 74 68 65 6e  n SQL NULL, then
f410: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
f420: 69 6f 6e 20 0a 6d 75 73 74 20 63 68 6f 6f 73 65  ion .must choose
f430: 20 61 20 72 6f 77 69 64 20 66 6f 72 20 74 68 65   a rowid for the
f440: 20 6e 65 77 6c 79 20 69 6e 73 65 72 74 65 64 20   newly inserted 
f450: 72 6f 77 2e 20 53 75 62 73 65 71 75 65 6e 74 20  row. Subsequent 
f460: 61 72 67 76 5b 5d 20 0a 65 6e 74 72 69 65 73 20  argv[] .entries 
f470: 63 6f 6e 74 61 69 6e 20 76 61 6c 75 65 73 20 6f  contain values o
f480: 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 20 6f 66  f the columns of
f490: 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
f4a0: 6c 65 2c 20 69 6e 20 74 68 65 20 0a 6f 72 64 65  le, in the .orde
f4b0: 72 20 74 68 61 74 20 74 68 65 20 63 6f 6c 75 6d  r that the colum
f4c0: 6e 73 20 77 65 72 65 20 64 65 63 6c 61 72 65 64  ns were declared
f4d0: 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  . The number of 
f4e0: 63 6f 6c 75 6d 6e 73 20 77 69 6c 6c 0a 6d 61 74  columns will.mat
f4f0: 63 68 20 74 68 65 20 74 61 62 6c 65 20 64 65 63  ch the table dec
f500: 6c 61 72 61 74 69 6f 6e 20 74 68 61 74 20 74 68  laration that th
f510: 65 20 3c 61 20 68 72 65 66 3d 22 76 74 61 62 2e  e <a href="vtab.
f520: 68 74 6d 6c 23 78 63 6f 6e 6e 65 63 74 22 3e 78  html#xconnect">x
f530: 43 6f 6e 6e 65 63 74 3c 2f 61 3e 20 6f 72 20 3c  Connect</a> or <
f540: 61 20 68 72 65 66 3d 22 76 74 61 62 2e 68 74 6d  a href="vtab.htm
f550: 6c 23 78 63 72 65 61 74 65 22 3e 78 43 72 65 61  l#xcreate">xCrea
f560: 74 65 3c 2f 61 3e 20 6d 65 74 68 6f 64 20 6d 61  te</a> method ma
f570: 64 65 20 0a 75 73 69 6e 67 20 74 68 65 20 3c 61  de .using the <a
f580: 20 68 72 65 66 3d 22 63 33 72 65 66 2f 64 65 63   href="c3ref/dec
f590: 6c 61 72 65 5f 76 74 61 62 2e 68 74 6d 6c 22 3e  lare_vtab.html">
f5a0: 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f  sqlite3_declare_
f5b0: 76 74 61 62 28 29 3c 2f 61 3e 20 63 61 6c 6c 2e  vtab()</a> call.
f5c0: 20 20 41 6c 6c 20 68 69 64 64 65 6e 20 63 6f 6c    All hidden col
f5d0: 75 6d 6e 73 20 61 72 65 20 69 6e 63 6c 75 64 65  umns are include
f5e0: 64 2e 0a 0a 3c 2f 70 3e 3c 70 3e 57 68 65 6e 20  d...</p><p>When 
f5f0: 64 6f 69 6e 67 20 61 6e 20 69 6e 73 65 72 74 20  doing an insert 
f600: 77 69 74 68 6f 75 74 20 61 20 72 6f 77 69 64 20  without a rowid 
f610: 28 61 72 67 63 3e 31 2c 20 61 72 67 76 5b 31 5d  (argc>1, argv[1]
f620: 20 69 73 20 61 6e 20 53 51 4c 20 4e 55 4c 4c 29   is an SQL NULL)
f630: 2c 0a 6f 6e 20 61 20 76 69 72 74 75 61 6c 20 74  ,.on a virtual t
f640: 61 62 6c 65 20 74 68 61 74 20 75 73 65 73 20 52  able that uses R
f650: 4f 57 49 44 20 28 62 75 74 20 6e 6f 74 20 6f 6e  OWID (but not on
f660: 20 61 20 3c 61 20 68 72 65 66 3d 22 76 74 61 62   a <a href="vtab
f670: 2e 68 74 6d 6c 23 77 6f 72 69 64 22 3e 57 49 54  .html#worid">WIT
f680: 48 4f 55 54 20 52 4f 57 49 44 20 76 69 72 74 75  HOUT ROWID virtu
f690: 61 6c 20 74 61 62 6c 65 3c 2f 61 3e 29 2c 0a 74  al table</a>),.t
f6a0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
f6b0: 6e 20 6d 75 73 74 20 73 65 74 20 2a 70 52 6f 77  n must set *pRow
f6c0: 69 64 20 74 6f 20 74 68 65 20 72 6f 77 69 64 20  id to the rowid 
f6d0: 6f 66 20 74 68 65 20 6e 65 77 6c 79 20 69 6e 73  of the newly ins
f6e0: 65 72 74 65 64 20 72 6f 77 3b 20 0a 74 68 69 73  erted row; .this
f6f0: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
f700: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
f710: 62 79 20 74 68 65 20 3c 61 20 68 72 65 66 3d 22  by the <a href="
f720: 63 33 72 65 66 2f 6c 61 73 74 5f 69 6e 73 65 72  c3ref/last_inser
f730: 74 5f 72 6f 77 69 64 2e 68 74 6d 6c 22 3e 73 71  t_rowid.html">sq
f740: 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
f750: 74 5f 72 6f 77 69 64 28 29 3c 2f 61 3e 0a 66 75  t_rowid()</a>.fu
f760: 6e 63 74 69 6f 6e 2e 20 53 65 74 74 69 6e 67 20  nction. Setting 
f770: 74 68 69 73 20 76 61 6c 75 65 20 69 6e 20 61 6c  this value in al
f780: 6c 20 74 68 65 20 6f 74 68 65 72 20 63 61 73 65  l the other case
f790: 73 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  s is a harmless 
f7a0: 6e 6f 2d 6f 70 3b 0a 74 68 65 20 53 51 4c 69 74  no-op;.the SQLit
f7b0: 65 20 65 6e 67 69 6e 65 20 69 67 6e 6f 72 65 73  e engine ignores
f7c0: 20 74 68 65 20 2a 70 52 6f 77 69 64 20 72 65 74   the *pRowid ret
f7d0: 75 72 6e 20 76 61 6c 75 65 20 69 66 20 61 72 67  urn value if arg
f7e0: 63 3d 3d 31 20 6f 72 20 0a 61 72 67 76 5b 31 5d  c==1 or .argv[1]
f7f0: 20 69 73 20 6e 6f 74 20 61 6e 20 53 51 4c 20 4e   is not an SQL N
f800: 55 4c 4c 2e 0a 0a 3c 2f 70 3e 3c 70 3e 45 61 63  ULL...</p><p>Eac
f810: 68 20 63 61 6c 6c 20 74 6f 20 78 55 70 64 61 74  h call to xUpdat
f820: 65 20 77 69 6c 6c 20 66 61 6c 6c 20 69 6e 74 6f  e will fall into
f830: 20 6f 6e 65 20 6f 66 20 63 61 73 65 73 20 73 68   one of cases sh
f840: 6f 77 6e 20 62 65 6c 6f 77 2e 0a 4e 6f 74 20 74  own below..Not t
f850: 68 61 74 20 72 65 66 65 72 65 6e 63 65 73 20 74  hat references t
f860: 6f 20 3c 62 3e 61 72 67 76 26 23 39 31 3b 69 26  o <b>argv&#91;i&
f870: 23 39 33 3c 2f 62 3e 20 6d 65 61 6e 20 74 68 65  #93</b> mean the
f880: 20 53 51 4c 20 76 61 6c 75 65 0a 68 65 6c 64 20   SQL value.held 
f890: 77 69 74 68 69 6e 20 74 68 65 20 61 72 67 76 26  within the argv&
f8a0: 23 39 31 3b 69 26 23 39 33 3b 20 6f 62 6a 65 63  #91;i&#93; objec
f8b0: 74 2c 20 6e 6f 74 20 74 68 65 20 61 72 67 76 26  t, not the argv&
f8c0: 23 39 31 3b 69 26 23 39 33 3b 0a 6f 62 6a 65 63  #91;i&#93;.objec
f8d0: 74 20 69 74 73 65 6c 66 2e 0a 0a 3c 2f 70 3e 3c  t itself...</p><
f8e0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 3c 64 6c 3e  blockquote>.<dl>
f8f0: 0a 3c 64 74 3e 3c 62 3e 61 72 67 63 20 3d 20 31  .<dt><b>argc = 1
f900: 20 3c 62 72 3e 20 61 72 67 76 5b 30 5d 20 26 6e   <br> argv[0] &n
f910: 65 3b 20 4e 55 4c 4c 3c 2f 62 3e 0a 3c 2f 64 74  e; NULL</b>.</dt
f920: 3e 3c 64 64 3e 3c 70 3e 0a 44 45 4c 45 54 45 3a  ><dd><p>.DELETE:
f930: 20 54 68 65 20 73 69 6e 67 6c 65 20 72 6f 77 20   The single row 
f940: 77 69 74 68 20 72 6f 77 69 64 20 6f 72 20 50 52  with rowid or PR
f950: 49 4d 41 52 59 20 4b 45 59 20 65 71 75 61 6c 20  IMARY KEY equal 
f960: 74 6f 20 61 72 67 76 5b 30 5d 20 69 73 20 64 65  to argv[0] is de
f970: 6c 65 74 65 64 2e 20 0a 4e 6f 20 69 6e 73 65 72  leted. .No inser
f980: 74 20 6f 63 63 75 72 73 2e 0a 0a 3c 2f 70 3e 3c  t occurs...</p><
f990: 2f 64 64 3e 3c 64 74 3e 3c 62 3e 61 72 67 63 20  /dd><dt><b>argc 
f9a0: 26 67 74 3b 20 31 20 3c 62 72 3e 20 61 72 67 76  &gt; 1 <br> argv
f9b0: 5b 30 5d 20 3d 20 4e 55 4c 4c 3c 2f 62 3e 0a 3c  [0] = NULL</b>.<
f9c0: 2f 64 74 3e 3c 64 64 3e 3c 70 3e 0a 49 4e 53 45  /dt><dd><p>.INSE
f9d0: 52 54 3a 20 41 20 6e 65 77 20 72 6f 77 20 69 73  RT: A new row is
f9e0: 20 69 6e 73 65 72 74 65 64 20 77 69 74 68 20 63   inserted with c
f9f0: 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20 74 61 6b  olumn values tak
fa00: 65 6e 20 66 72 6f 6d 0a 61 72 67 76 5b 32 5d 20  en from.argv[2] 
fa10: 61 6e 64 20 66 6f 6c 6c 6f 77 69 6e 67 2e 20 20  and following.  
fa20: 49 6e 20 61 20 72 6f 77 69 64 20 76 69 72 74 75  In a rowid virtu
fa30: 61 6c 20 74 61 62 6c 65 2c 20 69 66 20 61 72 67  al table, if arg
fa40: 76 5b 31 5d 20 69 73 20 61 6e 20 53 51 4c 20 4e  v[1] is an SQL N
fa50: 55 4c 4c 2c 0a 74 68 65 6e 20 61 20 6e 65 77 20  ULL,.then a new 
fa60: 75 6e 69 71 75 65 20 72 6f 77 69 64 20 69 73 20  unique rowid is 
fa70: 67 65 6e 65 72 61 74 65 64 20 61 75 74 6f 6d 61  generated automa
fa80: 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 61 72  tically.  The ar
fa90: 67 76 5b 31 5d 20 77 69 6c 6c 20 62 65 20 4e 55  gv[1] will be NU
faa0: 4c 4c 0a 66 6f 72 20 61 20 3c 61 20 68 72 65 66  LL.for a <a href
fab0: 3d 22 76 74 61 62 2e 68 74 6d 6c 23 77 6f 72 69  ="vtab.html#wori
fac0: 64 22 3e 57 49 54 48 4f 55 54 20 52 4f 57 49 44  d">WITHOUT ROWID
fad0: 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 3c 2f   virtual table</
fae0: 61 3e 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73  a>, in which cas
faf0: 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  e the implementa
fb00: 74 69 6f 6e 20 73 68 6f 75 6c 64 0a 74 61 6b 65  tion should.take
fb10: 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59   the PRIMARY KEY
fb20: 20 76 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 20   value from the 
fb30: 61 70 70 72 6f 70 72 69 61 74 65 20 63 6f 6c 75  appropriate colu
fb40: 6d 6e 20 69 6e 20 61 72 67 76 5b 32 5d 20 61 6e  mn in argv[2] an
fb50: 64 20 66 6f 6c 6c 6f 77 69 6e 67 2e 0a 0a 3c 2f  d following...</
fb60: 70 3e 3c 2f 64 64 3e 3c 64 74 3e 3c 62 3e 61 72  p></dd><dt><b>ar
fb70: 67 63 20 26 67 74 3b 20 31 20 3c 62 72 3e 20 61  gc &gt; 1 <br> a
fb80: 72 67 76 5b 30 5d 20 26 6e 65 3b 20 4e 55 4c 4c  rgv[0] &ne; NULL
fb90: 20 3c 62 72 3e 20 61 72 67 76 5b 30 5d 20 3d 20   <br> argv[0] = 
fba0: 61 72 67 76 5b 31 5d 3c 2f 62 3e 0a 3c 2f 64 74  argv[1]</b>.</dt
fbb0: 3e 3c 64 64 3e 3c 70 3e 0a 55 50 44 41 54 45 3a  ><dd><p>.UPDATE:
fbc0: 0a 54 68 65 20 72 6f 77 20 77 69 74 68 20 72 6f  .The row with ro
fbd0: 77 69 64 20 6f 72 20 50 52 49 4d 41 52 59 20 4b  wid or PRIMARY K
fbe0: 45 59 20 61 72 67 76 5b 30 5d 20 69 73 20 75 70  EY argv[0] is up
fbf0: 64 61 74 65 64 20 77 69 74 68 20 6e 65 77 20 76  dated with new v
fc00: 61 6c 75 65 73 20 0a 69 6e 20 61 72 67 76 5b 32  alues .in argv[2
fc10: 5d 20 61 6e 64 20 66 6f 6c 6c 6f 77 69 6e 67 20  ] and following 
fc20: 70 61 72 61 6d 65 74 65 72 73 2e 0a 0a 3c 2f 70  parameters...</p
fc30: 3e 3c 2f 64 64 3e 3c 64 74 3e 3c 62 3e 61 72 67  ></dd><dt><b>arg
fc40: 63 20 26 67 74 3b 20 31 20 3c 62 72 3e 20 61 72  c &gt; 1 <br> ar
fc50: 67 76 5b 30 5d 20 26 6e 65 3b 20 4e 55 4c 4c 20  gv[0] &ne; NULL 
fc60: 3c 62 72 3e 20 61 72 67 76 5b 30 5d 20 26 6e 65  <br> argv[0] &ne
fc70: 3b 20 61 72 67 76 5b 31 5d 3c 2f 62 3e 0a 3c 2f  ; argv[1]</b>.</
fc80: 64 74 3e 3c 64 64 3e 3c 70 3e 0a 55 50 44 41 54  dt><dd><p>.UPDAT
fc90: 45 20 77 69 74 68 20 72 6f 77 69 64 20 6f 72 20  E with rowid or 
fca0: 50 52 49 4d 41 52 59 20 4b 45 59 20 63 68 61 6e  PRIMARY KEY chan
fcb0: 67 65 3a 0a 54 68 65 20 72 6f 77 20 77 69 74 68  ge:.The row with
fcc0: 20 72 6f 77 69 64 20 6f 72 20 50 52 49 4d 41 52   rowid or PRIMAR
fcd0: 59 20 4b 45 59 20 61 72 67 76 5b 30 5d 20 69 73  Y KEY argv[0] is
fce0: 20 75 70 64 61 74 65 64 20 77 69 74 68 20 0a 74   updated with .t
fcf0: 68 65 20 72 6f 77 69 64 20 6f 72 20 50 52 49 4d  he rowid or PRIM
fd00: 41 52 59 20 4b 45 59 20 69 6e 20 61 72 67 76 5b  ARY KEY in argv[
fd10: 31 5d 20 0a 61 6e 64 20 6e 65 77 20 76 61 6c 75  1] .and new valu
fd20: 65 73 20 69 6e 20 61 72 67 76 5b 32 5d 20 61 6e  es in argv[2] an
fd30: 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 61 72 61  d following para
fd40: 6d 65 74 65 72 73 2e 20 54 68 69 73 20 77 69 6c  meters. This wil
fd50: 6c 20 6f 63 63 75 72 20 0a 77 68 65 6e 20 61 6e  l occur .when an
fd60: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75   SQL statement u
fd70: 70 64 61 74 65 73 20 61 20 72 6f 77 69 64 2c 20  pdates a rowid, 
fd80: 61 73 20 69 6e 20 74 68 65 20 73 74 61 74 65 6d  as in the statem
fd90: 65 6e 74 3a 0a 3c 2f 70 3e 3c 62 6c 6f 63 6b 71  ent:.</p><blockq
fda0: 75 6f 74 65 3e 0a 20 20 20 3c 61 20 68 72 65 66  uote>.   <a href
fdb0: 3d 22 6c 61 6e 67 5f 75 70 64 61 74 65 2e 68 74  ="lang_update.ht
fdc0: 6d 6c 22 3e 55 50 44 41 54 45 3c 2f 61 3e 20 74  ml">UPDATE</a> t
fdd0: 61 62 6c 65 20 53 45 54 20 72 6f 77 69 64 3d 72  able SET rowid=r
fde0: 6f 77 69 64 2b 31 20 57 48 45 52 45 20 2e 2e 2e  owid+1 WHERE ...
fdf0: 3b 20 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ; .</blockquote>
fe00: 0a 3c 2f 64 64 3e 3c 2f 64 6c 3e 0a 3c 2f 62 6c  .</dd></dl>.</bl
fe10: 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68  ockquote>..<p>Th
fe20: 65 20 78 55 70 64 61 74 65 20 6d 65 74 68 6f 64  e xUpdate method
fe30: 20 6d 75 73 74 20 72 65 74 75 72 6e 20 3c 61 20   must return <a 
fe40: 68 72 65 66 3d 22 72 65 73 63 6f 64 65 2e 68 74  href="rescode.ht
fe50: 6d 6c 23 6f 6b 22 3e 53 51 4c 49 54 45 5f 4f 4b  ml#ok">SQLITE_OK
fe60: 3c 2f 61 3e 20 69 66 20 61 6e 64 20 6f 6e 6c 79  </a> if and only
fe70: 20 69 66 20 69 74 20 69 73 0a 73 75 63 63 65 73   if it is.succes
fe80: 73 66 75 6c 2e 20 20 49 66 20 61 20 66 61 69 6c  sful.  If a fail
fe90: 75 72 65 20 6f 63 63 75 72 73 2c 20 74 68 65 20  ure occurs, the 
fea0: 78 55 70 64 61 74 65 20 6d 75 73 74 20 72 65 74  xUpdate must ret
feb0: 75 72 6e 20 61 6e 20 61 70 70 72 6f 70 72 69 61  urn an appropria
fec0: 74 65 0a 3c 61 20 68 72 65 66 3d 22 72 65 73 63  te.<a href="resc
fed0: 6f 64 65 2e 68 74 6d 6c 22 3e 65 72 72 6f 72 20  ode.html">error 
fee0: 63 6f 64 65 3c 2f 61 3e 2e 20 20 4f 6e 20 61 20  code</a>.  On a 
fef0: 66 61 69 6c 75 72 65 2c 20 74 68 65 20 70 56 54  failure, the pVT
ff00: 61 62 2d 3e 7a 45 72 72 4d 73 67 20 65 6c 65 6d  ab->zErrMsg elem
ff10: 65 6e 74 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c  ent may optional
ff20: 6c 79 0a 62 65 20 72 65 70 6c 61 63 65 64 20 77  ly.be replaced w
ff30: 69 74 68 20 65 72 72 6f 72 20 6d 65 73 73 61 67  ith error messag
ff40: 65 20 74 65 78 74 20 73 74 6f 72 65 64 20 69 6e  e text stored in
ff50: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
ff60: 64 20 66 72 6f 6d 20 53 51 4c 69 74 65 20 0a 75  d from SQLite .u
ff70: 73 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 73  sing functions s
ff80: 75 63 68 20 61 73 20 3c 61 20 68 72 65 66 3d 22  uch as <a href="
ff90: 63 33 72 65 66 2f 6d 70 72 69 6e 74 66 2e 68 74  c3ref/mprintf.ht
ffa0: 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 6d 70 72 69  ml">sqlite3_mpri
ffb0: 6e 74 66 28 29 3c 2f 61 3e 20 6f 72 20 3c 61 20  ntf()</a> or <a 
ffc0: 68 72 65 66 3d 22 63 33 72 65 66 2f 66 72 65 65  href="c3ref/free
ffd0: 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 6d  .html">sqlite3_m
ffe0: 61 6c 6c 6f 63 28 29 3c 2f 61 3e 2e 0a 0a 3c 2f  alloc()</a>...</
fff0: 70 3e 3c 70 3e 49 66 20 74 68 65 20 78 55 70 64  p><p>If the xUpd
10000 61 74 65 20 6d 65 74 68 6f 64 20 76 69 6f 6c 61  ate method viola
10010 74 65 73 20 73 6f 6d 65 20 63 6f 6e 73 74 72 61  tes some constra
10020 69 6e 74 20 6f 66 20 74 68 65 20 76 69 72 74 75  int of the virtu
10030 61 6c 20 74 61 62 6c 65 0a 28 69 6e 63 6c 75 64  al table.(includ
10040 69 6e 67 2c 20 62 75 74 20 6e 6f 74 20 6c 69 6d  ing, but not lim
10050 69 74 65 64 20 74 6f 2c 20 61 74 74 65 6d 70 74  ited to, attempt
10060 69 6e 67 20 74 6f 20 73 74 6f 72 65 20 61 20 76  ing to store a v
10070 61 6c 75 65 20 6f 66 20 74 68 65 20 77 72 6f 6e  alue of the wron
10080 67 20 0a 64 61 74 61 74 79 70 65 2c 20 61 74 74  g .datatype, att
10090 65 6d 70 74 69 6e 67 20 74 6f 20 73 74 6f 72 65  empting to store
100a0 20 61 20 76 61 6c 75 65 20 74 68 61 74 20 69 73   a value that is
100b0 20 74 6f 6f 0a 6c 61 72 67 65 20 6f 72 20 74 6f   too.large or to
100c0 6f 20 73 6d 61 6c 6c 2c 20 6f 72 20 61 74 74 65  o small, or atte
100d0 6d 70 74 69 6e 67 20 74 6f 20 63 68 61 6e 67 65  mpting to change
100e0 20 61 20 72 65 61 64 2d 6f 6e 6c 79 20 76 61 6c   a read-only val
100f0 75 65 29 20 74 68 65 6e 20 74 68 65 0a 78 55 70  ue) then the.xUp
10100 64 61 74 65 20 6d 75 73 74 20 66 61 69 6c 20 77  date must fail w
10110 69 74 68 20 61 6e 20 61 70 70 72 6f 70 72 69 61  ith an appropria
10120 74 65 20 3c 61 20 68 72 65 66 3d 22 72 65 73 63  te <a href="resc
10130 6f 64 65 2e 68 74 6d 6c 22 3e 65 72 72 6f 72 20  ode.html">error 
10140 63 6f 64 65 3c 2f 61 3e 2e 0a 0a 3c 2f 70 3e 3c  code</a>...</p><
10150 70 3e 49 66 20 74 68 65 20 78 55 70 64 61 74 65  p>If the xUpdate
10160 20 6d 65 74 68 6f 64 20 69 73 20 70 65 72 66 6f   method is perfo
10170 72 6d 69 6e 67 20 61 6e 20 55 50 44 41 54 45 2c  rming an UPDATE,
10180 20 74 68 65 6e 0a 3c 61 20 68 72 65 66 3d 22 63   then.<a href="c
10190 33 72 65 66 2f 76 61 6c 75 65 5f 62 6c 6f 62 2e  3ref/value_blob.
101a0 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 76 61  html">sqlite3_va
101b0 6c 75 65 5f 6e 6f 63 68 61 6e 67 65 28 58 29 3c  lue_nochange(X)<
101c0 2f 61 3e 20 63 61 6e 20 62 65 20 75 73 65 64 20  /a> can be used 
101d0 74 6f 20 64 69 73 63 6f 76 65 72 20 77 68 69 63  to discover whic
101e0 68 20 63 6f 6c 75 6d 6e 73 0a 6f 66 20 74 68 65  h columns.of the
101f0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 77   virtual table w
10200 65 72 65 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64  ere actually mod
10210 69 66 69 65 64 20 62 79 20 74 68 65 20 55 50 44  ified by the UPD
10220 41 54 45 0a 73 74 61 74 65 6d 65 6e 74 2e 20 20  ATE.statement.  
10230 54 68 65 20 3c 61 20 68 72 65 66 3d 22 63 33 72  The <a href="c3r
10240 65 66 2f 76 61 6c 75 65 5f 62 6c 6f 62 2e 68 74  ef/value_blob.ht
10250 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 76 61 6c 75  ml">sqlite3_valu
10260 65 5f 6e 6f 63 68 61 6e 67 65 28 58 29 3c 2f 61  e_nochange(X)</a
10270 3e 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  > interface retu
10280 72 6e 73 0a 74 72 75 65 20 66 6f 72 20 63 6f 6c  rns.true for col
10290 75 6d 6e 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  umns that do not
102a0 20 63 68 61 6e 67 65 2e 0a 4f 6e 20 65 76 65 72   change..On ever
102b0 79 20 55 50 44 41 54 45 2c 20 53 51 4c 69 74 65  y UPDATE, SQLite
102c0 20 77 69 6c 6c 20 66 69 72 73 74 20 69 6e 76 6f   will first invo
102d0 6b 65 0a 3c 61 20 68 72 65 66 3d 22 76 74 61 62  ke.<a href="vtab
102e0 2e 68 74 6d 6c 23 78 63 6f 6c 75 6d 6e 22 3e 78  .html#xcolumn">x
102f0 43 6f 6c 75 6d 6e 3c 2f 61 3e 20 73 65 70 61 72  Column</a> separ
10300 61 74 65 6c 79 20 66 6f 72 20 65 61 63 68 20 75  ately for each u
10310 6e 63 68 61 6e 67 69 6e 67 20 63 6f 6c 75 6d 6e  nchanging column
10320 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 74 6f   in the table to
10330 20 0a 6f 62 74 61 69 6e 20 74 68 65 20 76 61 6c   .obtain the val
10340 75 65 20 66 6f 72 20 74 68 61 74 20 63 6f 6c 75  ue for that colu
10350 6d 6e 2e 20 20 54 68 65 20 3c 61 20 68 72 65 66  mn.  The <a href
10360 3d 22 76 74 61 62 2e 68 74 6d 6c 23 78 63 6f 6c  ="vtab.html#xcol
10370 75 6d 6e 22 3e 78 43 6f 6c 75 6d 6e 3c 2f 61 3e  umn">xColumn</a>
10380 20 6d 65 74 68 6f 64 20 63 61 6e 0a 63 68 65 63   method can.chec
10390 6b 20 74 6f 20 73 65 65 20 69 66 20 74 68 65 20  k to see if the 
103a0 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 63 68 61 6e  column is unchan
103b0 67 65 64 20 61 74 20 74 68 65 20 53 51 4c 20 6c  ged at the SQL l
103c0 65 76 65 6c 0a 62 79 20 69 6e 76 6f 6b 69 6e 67  evel.by invoking
103d0 20 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f   <a href="c3ref/
103e0 76 74 61 62 5f 6e 6f 63 68 61 6e 67 65 2e 68 74  vtab_nochange.ht
103f0 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 76 74 61 62  ml">sqlite3_vtab
10400 5f 6e 6f 63 68 61 6e 67 65 28 29 3c 2f 61 3e 2e  _nochange()</a>.
10410 20 20 49 66 20 3c 61 20 68 72 65 66 3d 22 76 74    If <a href="vt
10420 61 62 2e 68 74 6d 6c 23 78 63 6f 6c 75 6d 6e 22  ab.html#xcolumn"
10430 3e 78 43 6f 6c 75 6d 6e 3c 2f 61 3e 20 73 65 65  >xColumn</a> see
10440 73 20 74 68 61 74 0a 74 68 65 20 63 6f 6c 75 6d  s that.the colum
10450 6e 20 69 73 20 6e 6f 74 20 62 65 69 6e 67 20 6d  n is not being m
10460 6f 64 69 66 69 65 64 2c 20 69 74 20 73 68 6f 75  odified, it shou
10470 6c 64 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75  ld return withou
10480 74 20 73 65 74 74 69 6e 67 20 0a 61 20 72 65 73  t setting .a res
10490 75 6c 74 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ult using one of
104a0 20 74 68 65 20 3c 61 20 68 72 65 66 3d 22 63 33   the <a href="c3
104b0 72 65 66 2f 72 65 73 75 6c 74 5f 62 6c 6f 62 2e  ref/result_blob.
104c0 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 72 65  html">sqlite3_re
104d0 73 75 6c 74 5f 78 78 78 78 78 28 29 3c 2f 61 3e  sult_xxxxx()</a>
104e0 0a 69 6e 74 65 72 66 61 63 65 73 2e 20 20 4f 6e  .interfaces.  On
104f0 6c 79 20 69 6e 20 74 68 61 74 20 63 61 73 65 20  ly in that case 
10500 3c 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f 76  <a href="c3ref/v
10510 61 6c 75 65 5f 62 6c 6f 62 2e 68 74 6d 6c 22 3e  alue_blob.html">
10520 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 6f  sqlite3_value_no
10530 63 68 61 6e 67 65 28 29 3c 2f 61 3e 20 77 69 6c  change()</a> wil
10540 6c 20 62 65 0a 74 72 75 65 20 77 69 74 68 69 6e  l be.true within
10550 20 74 68 65 20 78 55 70 64 61 74 65 20 6d 65 74   the xUpdate met
10560 68 6f 64 2e 20 20 49 66 20 3c 61 20 68 72 65 66  hod.  If <a href
10570 3d 22 76 74 61 62 2e 68 74 6d 6c 23 78 63 6f 6c  ="vtab.html#xcol
10580 75 6d 6e 22 3e 78 43 6f 6c 75 6d 6e 3c 2f 61 3e  umn">xColumn</a>
10590 20 64 6f 65 73 0a 69 6e 76 6f 6b 65 20 6f 6e 65   does.invoke one
105a0 20 6f 72 20 6d 6f 72 65 20 3c 61 20 68 72 65 66   or more <a href
105b0 3d 22 63 33 72 65 66 2f 72 65 73 75 6c 74 5f 62  ="c3ref/result_b
105c0 6c 6f 62 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65  lob.html">sqlite
105d0 33 5f 72 65 73 75 6c 74 5f 78 78 78 78 78 28 29  3_result_xxxxx()
105e0 3c 2f 61 3e 0a 69 6e 74 65 72 66 61 63 65 73 2c  </a>.interfaces,
105f0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 75 6e 64   then SQLite und
10600 65 72 73 74 61 6e 64 73 20 74 68 61 74 20 61 73  erstands that as
10610 20 61 20 63 68 61 6e 67 65 20 69 6e 20 74 68 65   a change in the
10620 20 76 61 6c 75 65 0a 6f 66 20 74 68 65 20 63 6f   value.of the co
10630 6c 75 6d 6e 20 61 6e 64 20 74 68 65 20 3c 61 20  lumn and the <a 
10640 68 72 65 66 3d 22 63 33 72 65 66 2f 76 61 6c 75  href="c3ref/valu
10650 65 5f 62 6c 6f 62 2e 68 74 6d 6c 22 3e 73 71 6c  e_blob.html">sql
10660 69 74 65 33 5f 76 61 6c 75 65 5f 6e 6f 63 68 61  ite3_value_nocha
10670 6e 67 65 28 29 3c 2f 61 3e 20 63 61 6c 6c 20 66  nge()</a> call f
10680 6f 72 20 74 68 61 74 0a 63 6f 6c 75 6d 6e 20 77  or that.column w
10690 69 74 68 69 6e 20 78 55 70 64 61 74 65 20 77 69  ithin xUpdate wi
106a0 6c 6c 20 72 65 74 75 72 6e 20 66 61 6c 73 65 2e  ll return false.
106b0 0a 0a 3c 2f 70 3e 3c 70 3e 54 68 65 72 65 20 6d  ..</p><p>There m
106c0 69 67 68 74 20 62 65 20 6f 6e 65 20 6f 72 20 6d  ight be one or m
106d0 6f 72 65 20 3c 61 20 68 72 65 66 3d 22 63 33 72  ore <a href="c3r
106e0 65 66 2f 76 74 61 62 5f 63 75 72 73 6f 72 2e 68  ef/vtab_cursor.h
106f0 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 76 74 61  tml">sqlite3_vta
10700 62 5f 63 75 72 73 6f 72 3c 2f 61 3e 20 6f 62 6a  b_cursor</a> obj
10710 65 63 74 73 20 6f 70 65 6e 20 61 6e 64 20 69 6e  ects open and in
10720 20 75 73 65 20 0a 6f 6e 20 74 68 65 20 76 69 72   use .on the vir
10730 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 73 74 61  tual table insta
10740 6e 63 65 20 61 6e 64 20 70 65 72 68 61 70 73 20  nce and perhaps 
10750 65 76 65 6e 20 6f 6e 20 74 68 65 20 72 6f 77 20  even on the row 
10760 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 0a 74  of the virtual.t
10770 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20 78 55  able when the xU
10780 70 64 61 74 65 20 6d 65 74 68 6f 64 20 69 73 20  pdate method is 
10790 69 6e 76 6f 6b 65 64 2e 20 20 54 68 65 20 69 6d  invoked.  The im
107a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 0a  plementation of.
107b0 78 55 70 64 61 74 65 20 6d 75 73 74 20 62 65 20  xUpdate must be 
107c0 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 74 74  prepared for att
107d0 65 6d 70 74 73 20 74 6f 20 64 65 6c 65 74 65 20  empts to delete 
107e0 6f 72 20 6d 6f 64 69 66 79 20 72 6f 77 73 20 6f  or modify rows o
107f0 66 20 74 68 65 20 74 61 62 6c 65 0a 6f 75 74 20  f the table.out 
10800 66 72 6f 6d 20 6f 74 68 65 72 20 65 78 69 73 74  from other exist
10810 69 6e 67 20 63 75 72 73 6f 72 73 2e 20 20 49 66  ing cursors.  If
10820 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
10830 6c 65 20 63 61 6e 6e 6f 74 20 61 63 63 6f 6d 6d  le cannot accomm
10840 6f 64 61 74 65 0a 73 75 63 68 20 63 68 61 6e 67  odate.such chang
10850 65 73 2c 20 74 68 65 20 78 55 70 64 61 74 65 20  es, the xUpdate 
10860 6d 65 74 68 6f 64 20 6d 75 73 74 20 72 65 74 75  method must retu
10870 72 6e 20 61 6e 20 3c 61 20 68 72 65 66 3d 22 72  rn an <a href="r
10880 65 73 63 6f 64 65 2e 68 74 6d 6c 22 3e 65 72 72  escode.html">err
10890 6f 72 20 63 6f 64 65 3c 2f 61 3e 2e 0a 0a 3c 2f  or code</a>...</
108a0 70 3e 3c 70 3e 54 68 65 20 78 55 70 64 61 74 65  p><p>The xUpdate
108b0 20 6d 65 74 68 6f 64 20 69 73 20 6f 70 74 69 6f   method is optio
108c0 6e 61 6c 2e 0a 49 66 20 74 68 65 20 78 55 70 64  nal..If the xUpd
108d0 61 74 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74  ate pointer in t
108e0 68 65 20 3c 61 20 68 72 65 66 3d 22 63 33 72 65  he <a href="c3re
108f0 66 2f 6d 6f 64 75 6c 65 2e 68 74 6d 6c 22 3e 73  f/module.html">s
10900 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3c 2f 61  qlite3_module</a
10910 3e 20 66 6f 72 20 61 20 76 69 72 74 75 61 6c 20  > for a virtual 
10920 74 61 62 6c 65 0a 69 73 20 61 20 4e 55 4c 4c 20  table.is a NULL 
10930 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68  pointer, then th
10940 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
10950 69 73 20 72 65 61 64 2d 6f 6e 6c 79 2e 0a 0a 0a  is read-only....
10960 3c 61 20 6e 61 6d 65 3d 22 78 66 69 6e 64 66 75  <a name="xfindfu
10970 6e 63 74 69 6f 6e 22 3e 3c 2f 61 3e 0a 0a 3c 2f  nction"></a>..</
10980 70 3e 3c 68 32 20 69 64 3d 22 74 68 65 5f 78 66  p><h2 id="the_xf
10990 69 6e 64 66 75 6e 63 74 69 6f 6e 5f 6d 65 74 68  indfunction_meth
109a0 6f 64 22 3e 3c 73 70 61 6e 3e 32 2e 31 34 2e 20  od"><span>2.14. 
109b0 3c 2f 73 70 61 6e 3e 54 68 65 20 78 46 69 6e 64  </span>The xFind
109c0 46 75 6e 63 74 69 6f 6e 20 4d 65 74 68 6f 64 3c  Function Method<
109d0 2f 68 32 3e 0a 0a 3c 64 69 76 20 63 6c 61 73 73  /h2>..<div class
109e0 3d 22 63 6f 64 65 62 6c 6f 63 6b 22 3e 3c 70 72  ="codeblock"><pr
109f0 65 3e 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e  e>int (*xFindFun
10a00 63 74 69 6f 6e 29 28 0a 20 20 73 71 6c 69 74 65  ction)(.  sqlite
10a10 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 0a 20  3_vtab *pVtab,. 
10a20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 63 6f 6e   int nArg,.  con
10a30 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a  st char *zName,.
10a40 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63    void (**pxFunc
10a50 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
10a60 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
10a70 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
10a80 2a 2a 70 70 41 72 67 0a 29 3b 0a 3c 2f 70 72 65  **ppArg.);.</pre
10a90 3e 3c 2f 64 69 76 3e 0a 0a 3c 70 3e 54 68 69 73  ></div>..<p>This
10aa0 20 6d 65 74 68 6f 64 20 69 73 20 63 61 6c 6c 65   method is calle
10ab0 64 20 64 75 72 69 6e 67 20 3c 61 20 68 72 65 66  d during <a href
10ac0 3d 22 63 33 72 65 66 2f 70 72 65 70 61 72 65 2e  ="c3ref/prepare.
10ad0 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 70 72  html">sqlite3_pr
10ae0 65 70 61 72 65 28 29 3c 2f 61 3e 20 74 6f 20 67  epare()</a> to g
10af0 69 76 65 20 74 68 65 20 76 69 72 74 75 61 6c 0a  ive the virtual.
10b00 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
10b10 74 69 6f 6e 20 61 6e 20 6f 70 70 6f 72 74 75 6e  tion an opportun
10b20 69 74 79 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  ity to overload 
10b30 66 75 6e 63 74 69 6f 6e 73 2e 20 0a 54 68 69 73  functions. .This
10b40 20 6d 65 74 68 6f 64 20 6d 61 79 20 62 65 20 73   method may be s
10b50 65 74 20 74 6f 20 4e 55 4c 4c 20 69 6e 20 77 68  et to NULL in wh
10b60 69 63 68 20 63 61 73 65 20 6e 6f 20 6f 76 65 72  ich case no over
10b70 6c 6f 61 64 69 6e 67 20 6f 63 63 75 72 73 2e 0a  loading occurs..
10b80 0a 3c 2f 70 3e 3c 70 3e 57 68 65 6e 20 61 20 66  .</p><p>When a f
10b90 75 6e 63 74 69 6f 6e 20 75 73 65 73 20 61 20 63  unction uses a c
10ba0 6f 6c 75 6d 6e 20 66 72 6f 6d 20 61 20 76 69 72  olumn from a vir
10bb0 74 75 61 6c 20 74 61 62 6c 65 20 61 73 20 69 74  tual table as it
10bc0 73 20 66 69 72 73 74 20 0a 61 72 67 75 6d 65 6e  s first .argumen
10bd0 74 2c 20 74 68 69 73 20 6d 65 74 68 6f 64 20 69  t, this method i
10be0 73 20 63 61 6c 6c 65 64 20 74 6f 20 73 65 65 20  s called to see 
10bf0 69 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  if the virtual t
10c00 61 62 6c 65 20 77 6f 75 6c 64 20 0a 6c 69 6b 65  able would .like
10c10 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
10c20 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 66   function. The f
10c30 69 72 73 74 20 74 68 72 65 65 20 70 61 72 61 6d  irst three param
10c40 65 74 65 72 73 20 61 72 65 20 69 6e 70 75 74 73  eters are inputs
10c50 3a 20 0a 74 68 65 20 76 69 72 74 75 61 6c 20 74  : .the virtual t
10c60 61 62 6c 65 2c 20 74 68 65 20 6e 75 6d 62 65 72  able, the number
10c70 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   of arguments to
10c80 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 61   the function, a
10c90 6e 64 20 74 68 65 20 0a 6e 61 6d 65 20 6f 66 20  nd the .name of 
10ca0 74 68 65 20 66 75 6e 63 74 69 6f 6e 2e 20 49 66  the function. If
10cb0 20 6e 6f 20 6f 76 65 72 6c 6f 61 64 69 6e 67 20   no overloading 
10cc0 69 73 20 64 65 73 69 72 65 64 2c 20 74 68 69 73  is desired, this
10cd0 20 6d 65 74 68 6f 64 0a 72 65 74 75 72 6e 73 20   method.returns 
10ce0 30 2e 20 54 6f 20 6f 76 65 72 6c 6f 61 64 20 74  0. To overload t
10cf0 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 74 68 69  he function, thi
10d00 73 20 6d 65 74 68 6f 64 20 77 72 69 74 65 73 20  s method writes 
10d10 74 68 65 20 6e 65 77 20 0a 66 75 6e 63 74 69 6f  the new .functio
10d20 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
10d30 20 69 6e 74 6f 20 2a 70 78 46 75 6e 63 20 61 6e   into *pxFunc an
10d40 64 20 77 72 69 74 65 73 20 75 73 65 72 20 64 61  d writes user da
10d50 74 61 20 69 6e 74 6f 20 2a 70 70 41 72 67 20 0a  ta into *ppArg .
10d60 61 6e 64 20 72 65 74 75 72 6e 73 20 31 2e 0a 0a  and returns 1...
10d70 3c 2f 70 3e 3c 70 3e 4e 6f 74 65 20 74 68 61 74  </p><p>Note that
10d80 20 69 6e 66 69 78 20 66 75 6e 63 74 69 6f 6e 73   infix functions
10d90 20 28 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f   (<a href="lang_
10da0 65 78 70 72 2e 68 74 6d 6c 23 6c 69 6b 65 22 3e  expr.html#like">
10db0 4c 49 4b 45 3c 2f 61 3e 2c 20 3c 61 20 68 72 65  LIKE</a>, <a hre
10dc0 66 3d 22 6c 61 6e 67 5f 65 78 70 72 2e 68 74 6d  f="lang_expr.htm
10dd0 6c 23 67 6c 6f 62 22 3e 47 4c 4f 42 3c 2f 61 3e  l#glob">GLOB</a>
10de0 2c 20 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f  , <a href="lang_
10df0 65 78 70 72 2e 68 74 6d 6c 23 72 65 67 65 78 70  expr.html#regexp
10e00 22 3e 52 45 47 45 58 50 3c 2f 61 3e 2c 20 61 6e  ">REGEXP</a>, an
10e10 64 20 3c 61 20 68 72 65 66 3d 22 6c 61 6e 67 5f  d <a href="lang_
10e20 65 78 70 72 2e 68 74 6d 6c 23 6d 61 74 63 68 22  expr.html#match"
10e30 3e 4d 41 54 43 48 3c 2f 61 3e 29 20 72 65 76 65  >MATCH</a>) reve
10e40 72 73 65 20 0a 74 68 65 20 6f 72 64 65 72 20 6f  rse .the order o
10e50 66 20 74 68 65 69 72 20 61 72 67 75 6d 65 6e 74  f their argument
10e60 73 2e 20 53 6f 20 22 6c 69 6b 65 28 41 2c 42 29  s. So "like(A,B)
10e70 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
10e80 74 6f 20 22 42 20 6c 69 6b 65 20 41 22 2e 20 0a  to "B like A". .
10e90 46 6f 72 20 74 68 65 20 66 6f 72 6d 20 22 42 20  For the form "B 
10ea0 6c 69 6b 65 20 41 22 20 74 68 65 20 42 20 74 65  like A" the B te
10eb0 72 6d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  rm is considered
10ec0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
10ed0 65 6e 74 20 0a 74 6f 20 74 68 65 20 66 75 6e 63  ent .to the func
10ee0 74 69 6f 6e 2e 20 42 75 74 20 66 6f 72 20 22 6c  tion. But for "l
10ef0 69 6b 65 28 41 2c 42 29 22 20 74 68 65 20 41 20  ike(A,B)" the A 
10f00 74 65 72 6d 20 69 73 20 63 6f 6e 73 69 64 65 72  term is consider
10f10 65 64 20 74 68 65 20 0a 66 69 72 73 74 20 61 72  ed the .first ar
10f20 67 75 6d 65 6e 74 2e 0a 0a 3c 2f 70 3e 3c 70 3e  gument...</p><p>
10f30 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  The function poi
10f40 6e 74 65 72 20 72 65 74 75 72 6e 65 64 20 62 79  nter returned by
10f50 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   this routine mu
10f60 73 74 20 62 65 20 76 61 6c 69 64 20 66 6f 72 0a  st be valid for.
10f70 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20  the lifetime of 
10f80 74 68 65 20 3c 61 20 68 72 65 66 3d 22 63 33 72  the <a href="c3r
10f90 65 66 2f 76 74 61 62 2e 68 74 6d 6c 22 3e 73 71  ef/vtab.html">sq
10fa0 6c 69 74 65 33 5f 76 74 61 62 3c 2f 61 3e 20 6f  lite3_vtab</a> o
10fb0 62 6a 65 63 74 20 67 69 76 65 6e 20 69 6e 20 74  bject given in t
10fc0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
10fd0 65 72 2e 0a 0a 3c 61 20 6e 61 6d 65 3d 22 78 42  er...<a name="xB
10fe0 65 67 69 6e 22 3e 3c 2f 61 3e 0a 0a 3c 2f 70 3e  egin"></a>..</p>
10ff0 3c 68 32 20 69 64 3d 22 74 68 65 5f 78 62 65 67  <h2 id="the_xbeg
11000 69 6e 5f 6d 65 74 68 6f 64 22 3e 3c 73 70 61 6e  in_method"><span
11010 3e 32 2e 31 35 2e 20 3c 2f 73 70 61 6e 3e 54 68  >2.15. </span>Th
11020 65 20 78 42 65 67 69 6e 20 4d 65 74 68 6f 64 3c  e xBegin Method<
11030 2f 68 32 3e 0a 0a 3c 64 69 76 20 63 6c 61 73 73  /h2>..<div class
11040 3d 22 63 6f 64 65 62 6c 6f 63 6b 22 3e 3c 70 72  ="codeblock"><pr
11050 65 3e 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28  e>int (*xBegin)(
11060 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
11070 54 61 62 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 64 69  Tab);.</pre></di
11080 76 3e 0a 0a 3c 70 3e 54 68 69 73 20 6d 65 74 68  v>..<p>This meth
11090 6f 64 20 62 65 67 69 6e 73 20 61 20 74 72 61 6e  od begins a tran
110a0 73 61 63 74 69 6f 6e 20 6f 6e 20 61 20 76 69 72  saction on a vir
110b0 74 75 61 6c 20 74 61 62 6c 65 2e 0a 54 68 69 73  tual table..This
110c0 20 69 73 20 6d 65 74 68 6f 64 20 69 73 20 6f 70   is method is op
110d0 74 69 6f 6e 61 6c 2e 20 20 54 68 65 20 78 42 65  tional.  The xBe
110e0 67 69 6e 20 70 6f 69 6e 74 65 72 20 6f 66 20 3c  gin pointer of <
110f0 61 20 68 72 65 66 3d 22 63 33 72 65 66 2f 6d 6f  a href="c3ref/mo
11100 64 75 6c 65 2e 68 74 6d 6c 22 3e 73 71 6c 69 74  dule.html">sqlit
11110 65 33 5f 6d 6f 64 75 6c 65 3c 2f 61 3e 0a 6d 61  e3_module</a>.ma
11120 79 20 62 65 20 4e 55 4c 4c 2e 0a 0a 3c 2f 70 3e  y be NULL...</p>
11130 3c 70 3e 54 68 69 73 20 6d 65 74 68 6f 64 20 69  <p>This method i
11140 73 20 61 6c 77 61 79 73 20 66 6f 6c 6c 6f 77 65  s always followe
11150 64 20 62 79 20 6f 6e 65 20 63 61 6c 6c 20 74 6f  d by one call to
11160 20 65 69 74 68 65 72 20 74 68 65 0a 3c 61 20 68   either the.<a h
11170 72 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23 78  ref="vtab.html#x
11180 63 6f 6d 6d 69 74 22 3e 78 43 6f 6d 6d 69 74 3c  commit">xCommit<
11190 2f 61 3e 20 6f 72 20 3c 61 20 68 72 65 66 3d 22  /a> or <a href="
111a0 76 74 61 62 2e 68 74 6d 6c 23 78 72 6f 6c 6c 62  vtab.html#xrollb
111b0 61 63 6b 22 3e 78 52 6f 6c 6c 62 61 63 6b 3c 2f  ack">xRollback</
111c0 61 3e 20 6d 65 74 68 6f 64 2e 20 20 56 69 72 74  a> method.  Virt
111d0 75 61 6c 20 74 61 62 6c 65 20 74 72 61 6e 73 61  ual table transa
111e0 63 74 69 6f 6e 73 20 64 6f 0a 6e 6f 74 20 6e 65  ctions do.not ne
111f0 73 74 2c 20 73 6f 20 74 68 65 20 78 42 65 67 69  st, so the xBegi
11200 6e 20 6d 65 74 68 6f 64 20 77 69 6c 6c 20 6e 6f  n method will no
11210 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 6d 6f 72  t be invoked mor
11220 65 20 74 68 61 6e 20 6f 6e 63 65 0a 6f 6e 20 61  e than once.on a
11230 20 73 69 6e 67 6c 65 20 76 69 72 74 75 61 6c 20   single virtual 
11240 74 61 62 6c 65 0a 77 69 74 68 6f 75 74 20 61 6e  table.without an
11250 20 69 6e 74 65 72 76 65 6e 69 6e 67 20 63 61 6c   intervening cal
11260 6c 20 74 6f 20 65 69 74 68 65 72 20 3c 61 20 68  l to either <a h
11270 72 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23 78  ref="vtab.html#x
11280 63 6f 6d 6d 69 74 22 3e 78 43 6f 6d 6d 69 74 3c  commit">xCommit<
11290 2f 61 3e 20 6f 72 20 3c 61 20 68 72 65 66 3d 22  /a> or <a href="
112a0 76 74 61 62 2e 68 74 6d 6c 23 78 72 6f 6c 6c 62  vtab.html#xrollb
112b0 61 63 6b 22 3e 78 52 6f 6c 6c 62 61 63 6b 3c 2f  ack">xRollback</
112c0 61 3e 2e 0a 4d 75 6c 74 69 70 6c 65 20 63 61 6c  a>..Multiple cal
112d0 6c 73 20 74 6f 20 6f 74 68 65 72 20 6d 65 74 68  ls to other meth
112e0 6f 64 73 20 63 61 6e 20 61 6e 64 20 6c 69 6b 65  ods can and like
112f0 6c 79 20 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e  ly will occur in
11300 20 62 65 74 77 65 65 6e 0a 74 68 65 20 78 42 65   between.the xBe
11310 67 69 6e 20 61 6e 64 20 74 68 65 20 63 6f 72 72  gin and the corr
11320 65 73 70 6f 6e 64 69 6e 67 20 3c 61 20 68 72 65  esponding <a hre
11330 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23 78 63 6f  f="vtab.html#xco
11340 6d 6d 69 74 22 3e 78 43 6f 6d 6d 69 74 3c 2f 61  mmit">xCommit</a
11350 3e 20 6f 72 20 3c 61 20 68 72 65 66 3d 22 76 74  > or <a href="vt
11360 61 62 2e 68 74 6d 6c 23 78 72 6f 6c 6c 62 61 63  ab.html#xrollbac
11370 6b 22 3e 78 52 6f 6c 6c 62 61 63 6b 3c 2f 61 3e  k">xRollback</a>
11380 2e 0a 0a 3c 61 20 6e 61 6d 65 3d 22 78 73 79 6e  ...<a name="xsyn
11390 63 22 3e 3c 2f 61 3e 0a 0a 3c 2f 70 3e 3c 68 32  c"></a>..</p><h2
113a0 20 69 64 3d 22 74 68 65 5f 78 73 79 6e 63 5f 6d   id="the_xsync_m
113b0 65 74 68 6f 64 22 3e 3c 73 70 61 6e 3e 32 2e 31  ethod"><span>2.1
113c0 36 2e 20 3c 2f 73 70 61 6e 3e 54 68 65 20 78 53  6. </span>The xS
113d0 79 6e 63 20 4d 65 74 68 6f 64 3c 2f 68 32 3e 0a  ync Method</h2>.
113e0 0a 3c 64 69 76 20 63 6c 61 73 73 3d 22 63 6f 64  .<div class="cod
113f0 65 62 6c 6f 63 6b 22 3e 3c 70 72 65 3e 69 6e 74  eblock"><pre>int
11400 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
11410 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
11420 3c 2f 70 72 65 3e 3c 2f 64 69 76 3e 0a 0a 0a 3c  </pre></div>...<
11430 70 3e 54 68 69 73 20 6d 65 74 68 6f 64 20 73 69  p>This method si
11440 67 6e 61 6c 73 20 74 68 65 20 73 74 61 72 74 20  gnals the start 
11450 6f 66 20 61 20 74 77 6f 2d 70 68 61 73 65 20 63  of a two-phase c
11460 6f 6d 6d 69 74 20 6f 6e 20 61 20 76 69 72 74 75  ommit on a virtu
11470 61 6c 0a 74 61 62 6c 65 2e 0a 54 68 69 73 20 69  al.table..This i
11480 73 20 6d 65 74 68 6f 64 20 69 73 20 6f 70 74 69  s method is opti
11490 6f 6e 61 6c 2e 20 20 54 68 65 20 78 53 79 6e 63  onal.  The xSync
114a0 20 70 6f 69 6e 74 65 72 20 6f 66 20 3c 61 20 68   pointer of <a h
114b0 72 65 66 3d 22 63 33 72 65 66 2f 6d 6f 64 75 6c  ref="c3ref/modul
114c0 65 2e 68 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f  e.html">sqlite3_
114d0 6d 6f 64 75 6c 65 3c 2f 61 3e 0a 6d 61 79 20 62  module</a>.may b
114e0 65 20 4e 55 4c 4c 2e 0a 0a 3c 2f 70 3e 3c 70 3e  e NULL...</p><p>
114f0 54 68 69 73 20 6d 65 74 68 6f 64 20 69 73 20 6f  This method is o
11500 6e 6c 79 20 69 6e 76 6f 6b 65 64 20 61 66 74 65  nly invoked afte
11510 72 20 63 61 6c 6c 20 74 6f 20 74 68 65 20 3c 61  r call to the <a
11520 20 68 72 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c   href="vtab.html
11530 23 78 42 65 67 69 6e 22 3e 78 42 65 67 69 6e 3c  #xBegin">xBegin<
11540 2f 61 3e 20 6d 65 74 68 6f 64 20 61 6e 64 0a 70  /a> method and.p
11550 72 69 6f 72 20 74 6f 20 61 6e 20 3c 61 20 68 72  rior to an <a hr
11560 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23 78 63  ef="vtab.html#xc
11570 6f 6d 6d 69 74 22 3e 78 43 6f 6d 6d 69 74 3c 2f  ommit">xCommit</
11580 61 3e 20 6f 72 20 3c 61 20 68 72 65 66 3d 22 76  a> or <a href="v
11590 74 61 62 2e 68 74 6d 6c 23 78 72 6f 6c 6c 62 61  tab.html#xrollba
115a0 63 6b 22 3e 78 52 6f 6c 6c 62 61 63 6b 3c 2f 61  ck">xRollback</a
115b0 3e 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  >.  In order to 
115c0 69 6d 70 6c 65 6d 65 6e 74 20 74 77 6f 2d 70 68  implement two-ph
115d0 61 73 65 0a 63 6f 6d 6d 69 74 2c 20 74 68 65 20  ase.commit, the 
115e0 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 6f 6e 20  xSync method on 
115f0 61 6c 6c 20 76 69 72 74 75 61 6c 20 74 61 62 6c  all virtual tabl
11600 65 73 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 72  es is invoked pr
11610 69 6f 72 20 74 6f 0a 69 6e 76 6f 6b 69 6e 67 20  ior to.invoking 
11620 74 68 65 20 3c 61 20 68 72 65 66 3d 22 76 74 61  the <a href="vta
11630 62 2e 68 74 6d 6c 23 78 63 6f 6d 6d 69 74 22 3e  b.html#xcommit">
11640 78 43 6f 6d 6d 69 74 3c 2f 61 3e 20 6d 65 74 68  xCommit</a> meth
11650 6f 64 20 6f 6e 20 61 6e 79 20 76 69 72 74 75 61  od on any virtua
11660 6c 20 74 61 62 6c 65 2e 20 20 49 66 20 61 6e 79  l table.  If any
11670 20 6f 66 20 74 68 65 20 0a 78 53 79 6e 63 20 6d   of the .xSync m
11680 65 74 68 6f 64 73 20 66 61 69 6c 2c 20 74 68 65  ethods fail, the
11690 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
116a0 69 6f 6e 20 69 73 20 72 6f 6c 6c 65 64 20 62 61  ion is rolled ba
116b0 63 6b 2e 0a 0a 3c 61 20 6e 61 6d 65 3d 22 78 63  ck...<a name="xc
116c0 6f 6d 6d 69 74 22 3e 3c 2f 61 3e 0a 0a 3c 2f 70  ommit"></a>..</p
116d0 3e 3c 68 32 20 69 64 3d 22 74 68 65 5f 78 63 6f  ><h2 id="the_xco
116e0 6d 6d 69 74 5f 6d 65 74 68 6f 64 22 3e 3c 73 70  mmit_method"><sp
116f0 61 6e 3e 32 2e 31 37 2e 20 3c 2f 73 70 61 6e 3e  an>2.17. </span>
11700 54 68 65 20 78 43 6f 6d 6d 69 74 20 4d 65 74 68  The xCommit Meth
11710 6f 64 3c 2f 68 32 3e 0a 0a 3c 64 69 76 20 63 6c  od</h2>..<div cl
11720 61 73 73 3d 22 63 6f 64 65 62 6c 6f 63 6b 22 3e  ass="codeblock">
11730 3c 70 72 65 3e 69 6e 74 20 28 2a 78 43 6f 6d 6d  <pre>int (*xComm
11740 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  it)(sqlite3_vtab
11750 20 2a 70 56 54 61 62 29 3b 0a 3c 2f 70 72 65 3e   *pVTab);.</pre>
11760 3c 2f 64 69 76 3e 0a 0a 3c 70 3e 54 68 69 73 20  </div>..<p>This 
11770 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 61 20  method causes a 
11780 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 74 72  virtual table tr
11790 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f 6d  ansaction to com
117a0 6d 69 74 2e 0a 54 68 69 73 20 69 73 20 6d 65 74  mit..This is met
117b0 68 6f 64 20 69 73 20 6f 70 74 69 6f 6e 61 6c 2e  hod is optional.
117c0 20 20 54 68 65 20 78 43 6f 6d 6d 69 74 20 70 6f    The xCommit po
117d0 69 6e 74 65 72 20 6f 66 20 3c 61 20 68 72 65 66  inter of <a href
117e0 3d 22 63 33 72 65 66 2f 6d 6f 64 75 6c 65 2e 68  ="c3ref/module.h
117f0 74 6d 6c 22 3e 73 71 6c 69 74 65 33 5f 6d 6f 64  tml">sqlite3_mod
11800 75 6c 65 3c 2f 61 3e 0a 6d 61 79 20 62 65 20 4e  ule</a>.may be N
11810 55 4c 4c 2e 0a 0a 3c 2f 70 3e 3c 70 3e 41 20 63  ULL...</p><p>A c
11820 61 6c 6c 20 74 6f 20 74 68 69 73 20 6d 65 74 68  all to this meth
11830 6f 64 20 61 6c 77 61 79 73 20 66 6f 6c 6c 6f 77  od always follow
11840 73 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  s a prior call t
11850 6f 20 3c 61 20 68 72 65 66 3d 22 76 74 61 62 2e  o <a href="vtab.
11860 68 74 6d 6c 23 78 42 65 67 69 6e 22 3e 78 42 65  html#xBegin">xBe
11870 67 69 6e 3c 2f 61 3e 20 61 6e 64 0a 3c 61 20 68  gin</a> and.<a h
11880 72 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23 78  ref="vtab.html#x
11890 73 79 6e 63 22 3e 78 53 79 6e 63 3c 2f 61 3e 2e  sync">xSync</a>.
118a0 0a 0a 0a 3c 61 20 6e 61 6d 65 3d 22 78 72 6f 6c  ...<a name="xrol
118b0 6c 62 61 63 6b 22 3e 3c 2f 61 3e 0a 0a 3c 2f 70  lback"></a>..</p
118c0 3e 3c 68 32 20 69 64 3d 22 74 68 65 5f 78 72 6f  ><h2 id="the_xro
118d0 6c 6c 62 61 63 6b 5f 6d 65 74 68 6f 64 22 3e 3c  llback_method"><
118e0 73 70 61 6e 3e 32 2e 31 38 2e 20 3c 2f 73 70 61  span>2.18. </spa
118f0 6e 3e 54 68 65 20 78 52 6f 6c 6c 62 61 63 6b 20  n>The xRollback 
11900 4d 65 74 68 6f 64 3c 2f 68 32 3e 0a 0a 3c 64 69  Method</h2>..<di
11910 76 20 63 6c 61 73 73 3d 22 63 6f 64 65 62 6c 6f  v class="codeblo
11920 63 6b 22 3e 3c 70 72 65 3e 69 6e 74 20 28 2a 78  ck"><pre>int (*x
11930 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65  Rollback)(sqlite
11940 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
11950 3c 2f 70 72 65 3e 3c 2f 64 69 76 3e 0a 0a 3c 70  </pre></div>..<p
11960 3e 54 68 69 73 20 6d 65 74 68 6f 64 20 63 61 75  >This method cau
11970 73 65 73 20 61 20 76 69 72 74 75 61 6c 20 74 61  ses a virtual ta
11980 62 6c 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  ble transaction 
11990 74 6f 20 72 6f 6c 6c 62 61 63 6b 2e 0a 54 68 69  to rollback..Thi
119a0 73 20 69 73 20 6d 65 74 68 6f 64 20 69 73 20 6f  s is method is o
119b0 70 74 69 6f 6e 61 6c 2e 20 20 54 68 65 20 78 52  ptional.  The xR
119c0 6f 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20  ollback pointer 
119d0 6f 66 20 3c 61 20 68 72 65 66 3d 22 63 33 72 65  of <a href="c3re
119e0 66 2f 6d 6f 64 75 6c 65 2e 68 74 6d 6c 22 3e 73  f/module.html">s
119f0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3c 2f 61  qlite3_module</a
11a00 3e 0a 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 0a  >.may be NULL...
11a10 3c 2f 70 3e 3c 70 3e 41 20 63 61 6c 6c 20 74 6f  </p><p>A call to
11a20 20 74 68 69 73 20 6d 65 74 68 6f 64 20 61 6c 77   this method alw
11a30 61 79 73 20 66 6f 6c 6c 6f 77 73 20 61 20 70 72  ays follows a pr
11a40 69 6f 72 20 63 61 6c 6c 20 74 6f 20 3c 61 20 68  ior call to <a h
11a50 72 65 66 3d 22 76 74 61 62 2e 68 74 6d 6c 23 78  ref="vtab.html#x
11a60 42 65 67 69 6e 22 3e 78 42 65 67 69 6e 3c 2f 61  Begin">xBegin</a
11a70 3e 2e 0a 0a 0a 3c 61 20 6e 61 6d 65 3d 22 78 72  >....<a name="xr
11a80 65 6e 61 6d 65 22 3e 3c 2f 61 3e 0a 0a 3c 2f 70  ename"></a>..</p
11a90 3e 3c 68 32 20 69 64 3d 22 74 68 65 5f 78 72 65  ><h2 id="the_xre
11aa0 6e 61 6d 65 5f 6d 65 74 68 6f 64 22 3e 3c 73 70  name_method"><sp
11ab0 61 6e 3e 32 2e 31 39 2e 20 3c 2f 73 70 61 6e 3e  an>2.19. </span>
11ac0 54 68 65 20 78 52 65 6e 61 6d 65 20 4d 65 74 68  The xRename Meth
11ad0 6f 64 3c 2f 68 32 3e 0a 0a 3c 64 69 76 20 63 6c  od</h2>..<div cl
11ae0 61 73 73 3d 22 63 6f 64 65 62 6c 6f 63 6b 22 3e  ass="codeblock">
11af0 3c 70 72 65 3e 69 6e 74 20 28 2a 78 52 65 6e 61  <pre>int (*xRena
11b00 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  me)(sqlite3_vtab
11b10 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63   *pVtab, const c
11b20 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 3c 2f 70 72  har *zNew);.</pr
11b30 65 3e 3c 2f 64 69 76 3e 0a 0a 3c 70 3e 54 68 69  e></div>..<p>Thi
11b40 73 20 6d 65 74 68 6f 64 20 70 72 6f 76 69 64 65  s method provide
11b50 73 20 6e 6f 74 69 66 69 63 61 74 69 6f 6e 20 74  s notification t
11b60 68 61 74 20 74 68 65 20 76 69 72 74 75 61 6c 20  hat the virtual 
11b70 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
11b80 74 69 6f 6e 0a 74 68 61 74 20 74 68 65 20 76 69  tion.that the vi
11b90 72 74 75 61 6c 20 74 61 62 6c 65 20 77 69 6c 6c  rtual table will
11ba0 20 62 65 20 67 69 76 65 6e 20 61 20 6e 65 77 20   be given a new 
11bb0 6e 61 6d 65 2e 20 0a 49 66 20 74 68 69 73 20 6d  name. .If this m
11bc0 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 3c 61  ethod returns <a
11bd0 20 68 72 65 66 3d 22 72 65 73 63 6f 64 65 2e 68   href="rescode.h
11be0 74 6d 6c 23 6f 6b 22 3e 53 51 4c 49 54 45 5f 4f  tml#ok">SQLITE_O
11bf0 4b 3c 2f 61 3e 20 74 68 65 6e 20 53 51 4c 69 74  K</a> then SQLit
11c00 65 20 72 65 6e 61 6d 65 73 20 74 68 65 20 74 61  e renames the ta
11c10 62 6c 65 2e 0a 49 66 20 74 68 69 73 20 6d 65 74  ble..If this met
11c20 68 6f 64 20 72 65 74 75 72 6e 73 20 61 6e 20 3c  hod returns an <
11c30 61 20 68 72 65 66 3d 22 72 65 73 63 6f 64 65 2e  a href="rescode.
11c40 68 74 6d 6c 22 3e 65 72 72 6f 72 20 63 6f 64 65  html">error code
11c50 3c 2f 61 3e 20 74 68 65 6e 20 74 68 65 20 72 65  </a> then the re
11c60 6e 61 6d 69 6e 67 20 69 73 20 70 72 65 76 65 6e  naming is preven
11c70 74 65 64 2e 0a 0a 3c 2f 70 3e 3c 70 3e 54 68 65  ted...</p><p>The
11c80 20 78 52 65 6e 61 6d 65 20 6d 65 74 68 6f 64 20   xRename method 
11c90 69 73 20 72 65 71 75 69 72 65 64 20 66 6f 72 20  is required for 
11ca0 65 76 65 72 79 20 76 69 72 74 75 61 6c 20 74 61  every virtual ta
11cb0 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
11cc0 6f 6e 2e 0a 0a 3c 61 20 6e 61 6d 65 3d 22 78 73  on...<a name="xs
11cd0 61 76 65 70 6f 69 6e 74 22 3e 3c 2f 61 3e 0a 0a  avepoint"></a>..
11ce0 3c 2f 70 3e 3c 68 32 20 69 64 3d 22 74 68 65 5f  </p><h2 id="the_
11cf0 78 73 61 76 65 70 6f 69 6e 74 5f 78 72 65 6c 65  xsavepoint_xrele
11d00 61 73 65 5f 61 6e 64 5f 78 72 6f 6c 6c 62 61 63  ase_and_xrollbac
11d10 6b 74 6f 5f 6d 65 74 68 6f 64 73 22 3e 3c 73 70  kto_methods"><sp
11d20 61 6e 3e 32 2e 32 30 2e 20 3c 2f 73 70 61 6e 3e  an>2.20. </span>
11d30 54 68 65 20 78 53 61 76 65 70 6f 69 6e 74 2c 20  The xSavepoint, 
11d40 78 52 65 6c 65 61 73 65 2c 20 61 6e 64 20 78 52  xRelease, and xR
11d50 6f 6c 6c 62 61 63 6b 54 6f 20 4d 65 74 68 6f 64  ollbackTo Method
11d60 73 3c 2f 68 32 3e 0a 0a 3c 64 69 76 20 63 6c 61  s</h2>..<div cla
11d70 73 73 3d 22 63 6f 64 65 62 6c 6f 63 6b 22 3e 3c  ss="codeblock"><
11d80 70 72 65 3e 69 6e 74 20 28 2a 78 53 61 76 65 70  pre>int (*xSavep
11d90 6f 69 6e 74 29 28 73 71 6c 69 74 65 33 5f 76 74  oint)(sqlite3_vt
11da0 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 29 3b  ab *pVtab, int);
11db0 0a 69 6e 74 20 28 2a 78 52 65 6c 65 61 73 65 29  .int (*xRelease)
11dc0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
11dd0 56 74 61 62 2c 20 69 6e 74 29 3b 0a 69 6e 74 20  Vtab, int);.int 
11de0 28 2a 78 52 6f 6c 6c 62 61 63 6b 54 6f 29 28 73  (*xRollbackTo)(s
11df0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
11e00 61 62 2c 20 69 6e 74 29 3b 0a 3c 2f 70 72 65 3e  ab, int);.</pre>
11e10 3c 2f 64 69 76 3e 0a 0a 3c 70 3e 0a 54 68 65 73  </div>..<p>.Thes
11e20 65 20 6d 65 74 68 6f 64 73 20 70 72 6f 76 69 64  e methods provid
11e30 65 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  e the virtual ta
11e40 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
11e50 6f 6e 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74  on an opportunit
11e60 79 20 74 6f 0a 69 6d 70 6c 65 6d 65 6e 74 20 6e  y to.implement n
11e70 65 73 74 65 64 20 74 72 61 6e 73 61 63 74 69 6f  ested transactio
11e80 6e 73 2e 20 20 54 68 65 79 20 61 72 65 20 61 6c  ns.  They are al
11e90 77 61 79 73 20 6f 70 74 69 6f 6e 61 6c 20 61 6e  ways optional an
11ea0 64 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 0a 63  d will only be.c
11eb0 61 6c 6c 65 64 20 69 6e 20 53 51 4c 69 74 65 20  alled in SQLite 
11ec0 3c 61 20 68 72 65 66 3d 22 72 65 6c 65 61 73 65  <a href="release
11ed0 6c 6f 67 2f 33 5f 37 5f 37 2e 68 74 6d 6c 22 3e  log/3_7_7.html">
11ee0 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 3c 2f 61  version 3.7.7</a
11ef0 3e 20 28 32 30 31 31 2d 30 36 2d 32 33 29 20 61  > (2011-06-23) a
11f00 6e 64 20 6c 61 74 65 72 2e 0a 3c 2f 70 3e 0a 0a  nd later..</p>..
11f10 3c 70 3e 0a 57 68 65 6e 20 78 53 61 76 65 70 6f  <p>.When xSavepo
11f20 69 6e 74 28 58 2c 4e 29 20 69 73 20 69 6e 76 6f  int(X,N) is invo
11f30 6b 65 64 2c 20 74 68 61 74 20 69 73 20 61 20 73  ked, that is a s
11f40 69 67 6e 61 6c 20 74 6f 20 74 68 65 20 76 69 72  ignal to the vir
11f50 74 75 61 6c 20 74 61 62 6c 65 20 58 0a 74 68 61  tual table X.tha
11f60 74 20 69 74 20 73 68 6f 75 6c 64 20 73 61 76 65  t it should save
11f70 20 69 74 73 20 63 75 72 72 65 6e 74 20 73 74 61   its current sta
11f80 74 65 20 61 73 20 73 61 76 65 70 6f 69 6e 74 20  te as savepoint 
11f90 4e 2e 20 20 0a 41 20 73 75 62 73 65 71 75 65 6e  N.  .A subsequen
11fa0 74 20 63 61 6c 6c 0a 74 6f 20 78 52 6f 6c 6c 62  t call.to xRollb
11fb0 61 63 6b 54 6f 28 58 2c 52 29 20 6d 65 61 6e 73  ackTo(X,R) means
11fc0 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 20   that the state 
11fd0 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  of the virtual t
11fe0 61 62 6c 65 20 73 68 6f 75 6c 64 20 72 65 74 75  able should retu
11ff0 72 6e 0a 74 6f 20 77 68 61 74 20 69 74 20 77 61  rn.to what it wa
12000 73 20 77 68 65 6e 20 78 53 61 76 65 70 6f 69 6e  s when xSavepoin
12010 74 28 58 2c 52 29 20 77 61 73 20 6c 61 73 74 20  t(X,R) was last 
12020 63 61 6c 6c 65 64 2e 20 20 0a 54 68 65 20 63 61  called.  .The ca
12030 6c 6c 0a 74 6f 20 78 52 6f 6c 6c 62 61 63 6b 54  ll.to xRollbackT
12040 6f 28 58 2c 52 29 20 77 69 6c 6c 20 69 6e 76 61  o(X,R) will inva
12050 6c 69 64 61 74 65 20 61 6c 6c 20 73 61 76 65 70  lidate all savep
12060 6f 69 6e 74 73 20 77 69 74 68 20 4e 3e 52 3b 20  oints with N>R; 
12070 6e 6f 6e 65 20 6f 66 20 74 68 65 0a 69 6e 76 61  none of the.inva
12080 6c 69 64 65 64 20 73 61 76 65 70 6f 69 6e 74 73  lided savepoints
12090 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20   will be rolled 
120a0 62 61 63 6b 20 6f 72 20 72 65 6c 65 61 73 65 64  back or released
120b0 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 0a 62   without first.b
120c0 65 69 6e 67 20 72 65 69 6e 69 74 69 61 6c 69 7a  eing reinitializ
120d0 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20  ed by a call to 
120e0 78 53 61 76 65 70 6f 69 6e 74 28 29 2e 20 20 0a  xSavepoint().  .
120f0 41 20 63 61 6c 6c 20 74 6f 20 78 52 65 6c 65 61  A call to xRelea
12100 73 65 28 58 2c 4d 29 20 69 6e 76 61 6c 69 64 61  se(X,M) invalida
12110 74 65 73 20 61 6c 6c 20 73 61 76 65 70 6f 69 6e  tes all savepoin
12120 74 73 20 77 68 65 72 65 20 4e 3e 3d 4d 2e 0a 3c  ts where N>=M..<
12130 2f 70 3e 0a 0a 3c 70 3e 0a 4e 6f 6e 65 20 6f 66  /p>..<p>.None of
12140 20 74 68 65 20 78 53 61 76 65 70 6f 69 6e 74 28   the xSavepoint(
12150 29 2c 20 78 52 65 6c 65 61 73 65 28 29 2c 20 6f  ), xRelease(), o
12160 72 20 78 52 6f 6c 6c 62 61 63 6b 54 6f 28 29 20  r xRollbackTo() 
12170 6d 65 74 68 6f 64 73 20 77 69 6c 6c 20 65 76 65  methods will eve
12180 72 0a 62 65 20 63 61 6c 6c 65 64 20 65 78 63 65  r.be called exce
12190 70 74 20 69 6e 20 62 65 74 77 65 65 6e 20 63 61  pt in between ca
121a0 6c 6c 73 20 74 6f 20 78 42 65 67 69 6e 28 29 20  lls to xBegin() 
121b0 61 6e 64 20 0a 65 69 74 68 65 72 20 78 43 6f 6d  and .either xCom
121c0 6d 69 74 28 29 20 6f 72 20 78 52 6f 6c 6c 62 61  mit() or xRollba
121d0 63 6b 28 29 2e 0a 3c 2f 70 3e 0a 0a              ck()..</p>..