Documentation Source Text

Hex Artifact Content
Login

Artifact d768bc62edee4f8422792313cbd5d80d5acdeeb340cd5472c7925c5a91ff8cd4:


0000: 3c 74 69 74 6c 65 3e 52 6f 77 69 64 20 54 61 62  <title>Rowid Tab
0010: 6c 65 73 3c 2f 74 69 74 6c 65 3e 0a 3c 74 63 6c  les</title>.<tcl
0020: 3e 0a 68 64 5f 6b 65 79 77 6f 72 64 73 20 7b 72  >.hd_keywords {r
0030: 6f 77 69 64 20 74 61 62 6c 65 7d 20 7b 72 6f 77  owid table} {row
0040: 69 64 20 74 61 62 6c 65 73 7d 0a 3c 2f 74 63 6c  id tables}.</tcl
0050: 3e 0a 3c 68 31 20 61 6c 69 67 6e 3d 22 63 65 6e  >.<h1 align="cen
0060: 74 65 72 22 3e 52 6f 77 69 64 20 54 61 62 6c 65  ter">Rowid Table
0070: 73 3c 2f 68 31 3e 0a 0a 3c 68 32 3e 31 2e 30 20  s</h1>..<h2>1.0 
0080: 44 65 66 69 6e 69 74 69 6f 6e 3c 2f 68 32 3e 0a  Definition</h2>.
0090: 0a 3c 70 3e 41 20 22 72 6f 77 69 64 20 74 61 62  .<p>A "rowid tab
00a0: 6c 65 22 20 69 73 20 61 6e 79 20 74 61 62 6c 65  le" is any table
00b0: 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 73 63   in an SQLite sc
00c0: 68 65 6d 61 20 74 68 61 74 0a 3c 75 6c 3e 0a 3c  hema that.<ul>.<
00d0: 6c 69 3e 69 73 20 3c 65 6d 3e 6e 6f 74 3c 2f 65  li>is <em>not</e
00e0: 6d 3e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  m> a [virtual ta
00f0: 62 6c 65 5d 2c 20 61 6e 64 0a 3c 6c 69 3e 69 73  ble], and.<li>is
0100: 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 61 20   <em>not</em> a 
0110: 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20  [WITHOUT ROWID] 
0120: 74 61 62 6c 65 2e 0a 3c 2f 75 6c 3e 0a 4d 6f 73  table..</ul>.Mos
0130: 74 20 74 61 62 6c 65 73 20 69 6e 20 61 20 74 79  t tables in a ty
0140: 70 69 63 61 6c 20 53 51 4c 69 74 65 20 64 61 74  pical SQLite dat
0150: 61 62 61 73 65 20 73 63 68 65 6d 61 20 61 72 65  abase schema are
0160: 20 72 6f 77 69 64 20 74 61 62 6c 65 73 2e 0a 0a   rowid tables...
0170: 3c 70 3e 52 6f 77 69 64 20 74 61 62 6c 65 73 20  <p>Rowid tables 
0180: 61 72 65 20 64 69 73 74 69 6e 67 75 69 73 68 65  are distinguishe
0190: 64 20 62 79 20 74 68 65 20 66 61 63 74 20 74 68  d by the fact th
01a0: 61 74 20 74 68 65 79 20 61 6c 6c 20 68 61 76 65  at they all have
01b0: 0a 61 20 75 6e 69 71 75 65 2c 20 6e 6f 6e 2d 4e  .a unique, non-N
01c0: 55 4c 4c 2c 20 73 69 67 6e 65 64 20 36 34 2d 62  ULL, signed 64-b
01d0: 69 74 20 69 6e 74 65 67 65 72 20 5b 72 6f 77 69  it integer [rowi
01e0: 64 5d 20 74 68 61 74 20 69 73 20 75 73 65 64 20  d] that is used 
01f0: 61 73 0a 74 68 65 20 61 63 63 65 73 73 20 6b 65  as.the access ke
0200: 79 20 66 6f 72 20 74 68 65 20 64 61 74 61 20 69  y for the data i
0210: 6e 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  n the underlying
0220: 20 5b 42 2d 74 72 65 65 5d 20 73 74 6f 72 61 67   [B-tree] storag
0230: 65 20 65 6e 67 69 6e 65 2e 0a 0a 3c 68 32 3e 32  e engine...<h2>2
0240: 2e 30 20 51 75 69 72 6b 73 3c 2f 68 32 3e 0a 0a  .0 Quirks</h2>..
0250: 3c 75 6c 3e 0a 3c 6c 69 3e 3c 70 3e 0a 54 68 65  <ul>.<li><p>.The
0260: 20 5b 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 6f   [PRIMARY KEY] o
0270: 66 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20  f a rowid table 
0280: 28 69 66 20 74 68 65 72 65 20 69 73 20 6f 6e 65  (if there is one
0290: 29 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74  ) is usually not
02a0: 20 74 68 65 0a 74 72 75 65 20 70 72 69 6d 61 72   the.true primar
02b0: 79 20 6b 65 79 20 66 6f 72 20 74 68 65 20 74 61  y key for the ta
02c0: 62 6c 65 2c 20 69 6e 20 74 68 65 20 73 65 6e 73  ble, in the sens
02d0: 65 20 74 68 61 74 20 69 74 20 69 73 20 6e 6f 74  e that it is not
02e0: 20 74 68 65 20 75 6e 69 71 75 65 0a 6b 65 79 20   the unique.key 
02f0: 75 73 65 64 20 62 79 20 74 68 65 20 75 6e 64 65  used by the unde
0300: 72 6c 79 69 6e 67 20 5b 42 2d 74 72 65 65 5d 20  rlying [B-tree] 
0310: 73 74 6f 72 61 67 65 20 65 6e 67 69 6e 65 2e 20  storage engine. 
0320: 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e 20 74   The exception t
0330: 6f 0a 74 68 69 73 20 72 75 6c 65 20 69 73 20 77  o.this rule is w
0340: 68 65 6e 20 74 68 65 20 72 6f 77 69 64 20 74 61  hen the rowid ta
0350: 62 6c 65 20 64 65 63 6c 61 72 65 73 20 61 6e 20  ble declares an 
0360: 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
0370: 20 4b 45 59 5d 2e 0a 49 6e 20 74 68 65 20 65 78   KEY]..In the ex
0380: 63 65 70 74 69 6f 6e 2c 20 74 68 65 20 49 4e 54  ception, the INT
0390: 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
03a0: 20 62 65 63 6f 6d 65 73 20 61 6e 20 61 6c 69 61   becomes an alia
03b0: 73 20 66 6f 72 20 74 68 65 20 0a 5b 72 6f 77 69  s for the .[rowi
03c0: 64 5d 2e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 54 68 65  d]...<li><p>.The
03d0: 20 74 72 75 65 20 70 72 69 6d 61 72 79 20 6b 65   true primary ke
03e0: 79 20 66 6f 72 20 61 20 72 6f 77 69 64 20 74 61  y for a rowid ta
03f0: 62 6c 65 20 28 74 68 65 20 76 61 6c 75 65 20 74  ble (the value t
0400: 68 61 74 20 69 73 20 75 73 65 64 20 61 73 20 74  hat is used as t
0410: 68 65 0a 6b 65 79 20 74 6f 20 6c 6f 6f 6b 20 75  he.key to look u
0420: 70 20 72 6f 77 73 20 69 6e 20 74 68 65 20 75 6e  p rows in the un
0430: 64 65 72 6c 79 69 6e 67 20 5b 42 2d 74 72 65 65  derlying [B-tree
0440: 5d 20 73 74 6f 72 61 67 65 20 65 6e 67 69 6e 65  ] storage engine
0450: 29 0a 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  ).is the [rowid]
0460: 2e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 54 68 65 20 50  ...<li><p>.The P
0470: 52 49 4d 41 52 59 20 4b 45 59 20 63 6f 6e 73 74  RIMARY KEY const
0480: 72 61 69 6e 74 20 66 6f 72 20 61 20 72 6f 77 69  raint for a rowi
0490: 64 20 74 61 62 6c 65 20 28 61 73 20 6c 6f 6e 67  d table (as long
04a0: 20 61 73 20 69 74 20 69 73 20 6e 6f 74 0a 74 68   as it is not.th
04b0: 65 20 74 72 75 65 20 70 72 69 6d 61 72 79 20 6b  e true primary k
04c0: 65 79 20 6f 72 20 49 4e 54 45 47 45 52 20 50 52  ey or INTEGER PR
04d0: 49 4d 41 52 59 20 4b 45 59 29 20 69 73 20 72 65  IMARY KEY) is re
04e0: 61 6c 6c 79 20 74 68 65 20 73 61 6d 65 20 74 68  ally the same th
04f0: 69 6e 67 0a 61 73 20 61 20 5b 55 4e 49 51 55 45  ing.as a [UNIQUE
0500: 20 63 6f 6e 73 74 72 61 69 6e 74 5d 2e 20 20 42   constraint].  B
0510: 65 63 61 75 73 65 20 69 74 20 69 73 20 6e 6f 74  ecause it is not
0520: 20 61 20 74 72 75 65 20 70 72 69 6d 61 72 79 20   a true primary 
0530: 6b 65 79 2c 0a 63 6f 6c 75 6d 6e 73 20 6f 66 20  key,.columns of 
0540: 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59 20  the PRIMARY KEY 
0550: 61 72 65 20 61 6c 6c 6f 77 65 64 20 74 6f 20 62  are allowed to b
0560: 65 20 4e 55 4c 4c 2c 20 69 6e 20 76 69 6f 6c 61  e NULL, in viola
0570: 74 69 6f 6e 20 6f 66 0a 61 6c 6c 20 53 51 4c 20  tion of.all SQL 
0580: 73 74 61 6e 64 61 72 64 73 2e 0a 0a 3c 6c 69 3e  standards...<li>
0590: 3c 70 3e 0a 54 68 65 20 5b 72 6f 77 69 64 5d 20  <p>.The [rowid] 
05a0: 6f 66 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65  of a rowid table
05b0: 20 63 61 6e 20 62 65 20 61 63 63 65 73 73 65 64   can be accessed
05c0: 20 28 6f 72 20 63 68 61 6e 67 65 64 29 20 62 79   (or changed) by
05d0: 20 72 65 61 64 69 6e 67 20 6f 72 0a 77 72 69 74   reading or.writ
05e0: 69 6e 67 20 74 6f 20 61 6e 79 20 6f 66 20 74 68  ing to any of th
05f0: 65 20 22 72 6f 77 69 64 22 20 6f 72 20 22 6f 69  e "rowid" or "oi
0600: 64 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20  d" or "_rowid_" 
0610: 63 6f 6c 75 6d 6e 73 2e 20 20 45 78 63 65 70 74  columns.  Except
0620: 2c 0a 69 66 20 74 68 65 72 65 20 69 73 20 61 20  ,.if there is a 
0630: 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73  declared columns
0640: 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 74 68   in the table th
0650: 61 74 20 75 73 65 20 74 68 6f 73 65 0a 73 70 65  at use those.spe
0660: 63 69 61 6c 20 6e 61 6d 65 73 2c 20 74 68 65 6e  cial names, then
0670: 20 74 68 6f 73 65 20 6e 61 6d 65 73 20 72 65 66   those names ref
0680: 65 72 20 74 6f 20 74 68 65 20 64 65 63 6c 61 72  er to the declar
0690: 65 64 20 63 6f 6c 75 6d 6e 73 2c 20 6e 6f 74 20  ed columns, not 
06a0: 74 6f 0a 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  to.the underlyin
06b0: 67 20 5b 72 6f 77 69 64 5d 2e 0a 0a 3c 6c 69 3e  g [rowid]...<li>
06c0: 3c 70 3e 0a 41 63 63 65 73 73 20 74 6f 20 72 65  <p>.Access to re
06d0: 63 6f 72 64 73 20 76 69 61 20 5b 72 6f 77 69 64  cords via [rowid
06e0: 5d 20 69 73 20 68 69 67 68 6c 79 20 6f 70 74 69  ] is highly opti
06f0: 6d 69 7a 65 64 20 61 6e 64 20 76 65 72 79 20 66  mized and very f
0700: 61 73 74 2e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 49 66  ast...<li><p>.If
0710: 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 69 73 20   the [rowid] is 
0720: 6e 6f 74 20 61 6c 69 61 73 65 64 20 62 79 20 5b  not aliased by [
0730: 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
0740: 4b 45 59 5d 20 74 68 65 6e 20 69 74 20 69 73 20  KEY] then it is 
0750: 6e 6f 74 0a 70 65 72 73 69 73 74 65 6e 74 20 61  not.persistent a
0760: 6e 64 20 6d 69 67 68 74 20 63 68 61 6e 67 65 2e  nd might change.
0770: 20 20 49 6e 20 70 61 72 74 69 63 75 6c 61 72 20    In particular 
0780: 74 68 65 20 5b 56 41 43 55 55 4d 5d 20 63 6f 6d  the [VACUUM] com
0790: 6d 61 6e 64 20 77 69 6c 6c 0a 63 68 61 6e 67 65  mand will.change
07a0: 20 72 6f 77 69 64 73 20 66 6f 72 20 74 61 62 6c   rowids for tabl
07b0: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 64  es that do not d
07c0: 65 63 6c 61 72 65 20 61 6e 20 49 4e 54 45 47 45  eclare an INTEGE
07d0: 52 20 50 52 49 4d 41 52 59 20 4b 45 59 2e 0a 54  R PRIMARY KEY..T
07e0: 68 65 72 65 66 6f 72 65 2c 20 61 70 70 6c 69 63  herefore, applic
07f0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
0800: 74 20 6e 6f 72 6d 61 6c 6c 79 20 61 63 63 65 73  t normally acces
0810: 73 20 74 68 65 20 72 6f 77 69 64 20 64 69 72 65  s the rowid dire
0820: 63 74 6c 79 2c 0a 62 75 74 20 69 6e 73 74 65 61  ctly,.but instea
0830: 64 20 75 73 65 20 61 6e 20 49 4e 54 45 47 45 52  d use an INTEGER
0840: 20 50 52 49 4d 41 52 59 20 4b 45 59 2e 0a 0a 3c   PRIMARY KEY...<
0850: 6c 69 3e 3c 70 3e 0a 49 6e 20 74 68 65 20 75 6e  li><p>.In the un
0860: 64 65 72 6c 79 69 6e 67 20 5b 66 69 6c 65 20 66  derlying [file f
0870: 6f 72 6d 61 74 5d 2c 20 65 61 63 68 20 72 6f 77  ormat], each row
0880: 69 64 20 69 73 20 73 74 6f 72 65 64 20 61 73 20  id is stored as 
0890: 61 0a 5b 76 61 72 69 61 62 6c 65 2d 6c 65 6e 67  a.[variable-leng
08a0: 74 68 20 69 6e 74 65 67 65 72 5d 2e 20 20 54 68  th integer].  Th
08b0: 61 74 20 6d 65 61 6e 73 20 74 68 61 74 20 73 6d  at means that sm
08c0: 61 6c 6c 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  all non-negative
08d0: 0a 72 6f 77 69 64 20 76 61 6c 75 65 73 20 74 61  .rowid values ta
08e0: 6b 65 20 75 70 20 6c 65 73 73 20 64 69 73 6b 20  ke up less disk 
08f0: 73 70 61 63 65 20 74 68 61 6e 20 6c 61 72 67 65  space than large
0900: 20 6f 72 20 6e 65 67 61 74 69 76 65 0a 72 6f 77   or negative.row
0910: 69 64 20 76 61 6c 75 65 73 2e 0a 0a 3c 6c 69 3e  id values...<li>
0920: 3c 70 3e 0a 41 6c 6c 20 6f 66 20 74 68 65 20 63  <p>.All of the c
0930: 6f 6d 70 6c 69 63 61 74 69 6f 6e 73 20 61 62 6f  omplications abo
0940: 76 65 20 28 61 6e 64 20 6f 74 68 65 72 73 20 6e  ve (and others n
0950: 6f 74 20 6d 65 6e 74 69 6f 6e 65 64 20 68 65 72  ot mentioned her
0960: 65 29 0a 61 72 69 73 65 20 66 72 6f 6d 20 74 68  e).arise from th
0970: 65 20 6e 65 65 64 20 74 6f 20 70 72 65 73 65 72  e need to preser
0980: 76 65 20 62 61 63 6b 77 61 72 64 73 0a 63 6f 6d  ve backwards.com
0990: 70 61 74 69 62 69 6c 69 74 79 20 66 6f 72 20 74  patibility for t
09a0: 68 65 20 68 75 6e 64 72 65 64 73 20 6f 66 20 62  he hundreds of b
09b0: 69 6c 6c 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  illions of SQLit
09c0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  e database files
09d0: 20 69 6e 0a 63 69 72 63 75 6c 61 74 69 6f 6e 2e   in.circulation.
09e0: 20 20 49 6e 20 61 20 70 65 72 66 65 63 74 20 77    In a perfect w
09f0: 6f 72 6c 64 2c 20 74 68 65 72 65 20 77 6f 75 6c  orld, there woul
0a00: 64 20 62 65 20 6e 6f 20 73 75 63 68 20 74 68 69  d be no such thi
0a10: 6e 67 20 61 73 20 61 20 22 72 6f 77 69 64 22 0a  ng as a "rowid".
0a20: 61 6e 64 20 61 6c 6c 20 74 61 62 6c 65 73 20 77  and all tables w
0a30: 6f 75 6c 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  ould following t
0a40: 68 65 20 73 74 61 6e 64 61 72 64 20 73 65 6d 61  he standard sema
0a50: 6e 74 69 63 73 20 69 6d 70 6c 65 6d 65 6e 74 65  ntics implemente
0a60: 64 20 61 73 0a 5b 57 49 54 48 4f 55 54 20 52 4f  d as.[WITHOUT RO
0a70: 57 49 44 5d 20 74 61 62 6c 65 73 2c 20 6f 6e 6c  WID] tables, onl
0a80: 79 20 77 69 74 68 6f 75 74 20 74 68 65 20 65 78  y without the ex
0a90: 74 72 61 20 22 57 49 54 48 4f 55 54 20 52 4f 57  tra "WITHOUT ROW
0aa0: 49 44 22 20 6b 65 79 77 6f 72 64 73 2e 0a 55 6e  ID" keywords..Un
0ab0: 66 6f 72 74 75 6e 61 74 65 6c 79 2c 20 6c 69 66  fortunately, lif
0ac0: 65 20 69 73 20 6d 65 73 73 79 2e 20 20 54 68 65  e is messy.  The
0ad0: 20 64 65 73 69 67 6e 65 72 20 6f 66 20 53 51 4c   designer of SQL
0ae0: 69 74 65 20 6f 66 66 65 72 73 20 68 69 73 0a 73  ite offers his.s
0af0: 69 6e 63 65 72 65 20 61 70 6f 6c 6f 67 79 20 66  incere apology f
0b00: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 6d  or the current m
0b10: 65 73 73 2e 0a 3c 2f 75 6c 3e 0a                 ess..</ul>.