Documentation Source Text

Check-in [a8cbed7cc9]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Improvements and fixes to the eponymous virtual table documentation.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: a8cbed7cc9a3df72b059d7b68461b27ec9f18f9d
User & Date: drh 2015-09-11 17:17:27.631
Context
2015-09-11
20:19
Update the requirements.html document to provide links into the matrix for each requirement. (check-in: a6da4c726a user: drh tags: trunk)
17:17
Improvements and fixes to the eponymous virtual table documentation. (check-in: a8cbed7cc9 user: drh tags: trunk)
16:14
Minor updates to json1 and table-valued function documentation. (check-in: af1be7762c user: drh tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to pages/vtab.in.
︙︙
52
53
54
55
56
57
58
59



60





61
62
63
64
65
66
67
68
69
70
71
72
73

74

75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

94
95
96
97
98
99
100
101
102
103

104
105
106
107
108
109
110
111
112
113
114

<li> Access the filesystem of the host computer as if it were a database table
<li> Enabling SQL manipulation of data in statistics packages like R
</ul>

<h3>1.1 Usage</h3>

<p>A virtual table is created using a [CREATE VIRTUAL TABLE] statement.
This statement creates a table with a particular name and associates the



table with a "module".






<blockquote><pre>
   CREATE VIRTUAL TABLE tablename USING modulename;
</pre></blockquote>

<p>One can also provide comma-separated arguments to the module following 
the module name:

<blockquote><pre>
   CREATE VIRTUAL TABLE tablename USING modulename(arg1, arg2, ...);
</pre></blockquote>

<p>The format of the arguments to the module is very general. Each argument 

can consist of keywords, string literals, identifiers, numbers, and 

punctuation. The arguments are passed as written (as text) into the
[xCreate | constructor method] of the virtual table implementation 
when the virtual 
table is created and that constructor is responsible for parsing and 
interpreting the arguments. The argument syntax is sufficiently general 
that a virtual table implementation can, if it wants to, interpret its
arguments as [column definitions] in an ordinary [CREATE TABLE] statement. 
The implementation could also impose some other interpretation on the 
arguments.

<p>Once a virtual table has been created, it can be used like any other 
table with the exceptions noted above and imposed by specific virtual
table implementations. A virtual table is destroyed using the ordinary
[DROP TABLE] syntax.

<h4>1.1.1 Temporary virtual tables</h4>

<p>There is no "CREATE TEMP VIRTUAL TABLE" statement.  To create a
temporary virtual table, add the "temp" schema name before the tablename:


<blockcuqote><pre>
   CREATE VIRTUAL TABLE <b>temp.</b>tablename USING module(arg1, ...);
</pre></blockquote>

<tcl>hd_fragment epovtab {eponymous virtual tables}  \
        {eponymous virtual table}</tcl>
<h4>1.1.2 Eponymous virtual tables</h4>

<p>Some virtual tables exist automatically in every schema in which their

module is registered, even without a [CREATE VIRTUAL TABLE] statement.
Such virtual tables are called "eponymous virtual tables".
To use an eponymous virtual table, simple use the module name as if
it were a table.
Eponymous virtual tables exist in the "main" schema only, so they will
not work if prefixed with a different schema name.

<p>An example of an eponymous virtual table is the [dbstat virtual table].
To use the dbstat virtual table as an eponymous virtual table, 
simply query against the "dbstat"
module name, as if it were an ordinary table.  (Note that SQLite








|
>
>
>
|
>
>
>
>
>












|
>
|
>
|

















|
>









|
>


|
|








52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

<li> Access the filesystem of the host computer as if it were a database table
<li> Enabling SQL manipulation of data in statistics packages like R
</ul>

<h3>1.1 Usage</h3>

<p>A virtual table is created using a [CREATE VIRTUAL TABLE] statement.

<tcl>
RecursiveBubbleDiagram create-virtual-table-stmt
</tcl>

<p>The CREATE VIRTUAL TABLE statement creates a new table
called <yyterm>table-name</yyterm> derived from the class
class <yyterm>module-name</yyterm>.  The <yyterm>module-name</yyterm>
is the name that is registered for the virtual table by
the [sqlite3_create_module()] interface.

<blockquote><pre>
   CREATE VIRTUAL TABLE tablename USING modulename;
</pre></blockquote>

<p>One can also provide comma-separated arguments to the module following 
the module name:

<blockquote><pre>
   CREATE VIRTUAL TABLE tablename USING modulename(arg1, arg2, ...);
</pre></blockquote>

<p>The format of the arguments to the module is very general. Each 
<yyterm>module-argument</yyterm>
may contain keywords, string literals, identifiers, numbers, and 
punctuation. Each <yyterm>module-argument</yyterm> is passed as 
written (as text) into the
[xCreate | constructor method] of the virtual table implementation 
when the virtual 
table is created and that constructor is responsible for parsing and 
interpreting the arguments. The argument syntax is sufficiently general 
that a virtual table implementation can, if it wants to, interpret its
arguments as [column definitions] in an ordinary [CREATE TABLE] statement. 
The implementation could also impose some other interpretation on the 
arguments.

<p>Once a virtual table has been created, it can be used like any other 
table with the exceptions noted above and imposed by specific virtual
table implementations. A virtual table is destroyed using the ordinary
[DROP TABLE] syntax.

<h4>1.1.1 Temporary virtual tables</h4>

<p>There is no "CREATE TEMP VIRTUAL TABLE" statement.  To create a
temporary virtual table, add the "temp" schema
before the virtual table name.

<blockcuqote><pre>
   CREATE VIRTUAL TABLE <b>temp.</b>tablename USING module(arg1, ...);
</pre></blockquote>

<tcl>hd_fragment epovtab {eponymous virtual tables}  \
        {eponymous virtual table}</tcl>
<h4>1.1.2 Eponymous virtual tables</h4>

<p>Some virtual tables exist automatically in the "main" schema of
every database connection in which their
module is registered, even without a [CREATE VIRTUAL TABLE] statement.
Such virtual tables are called "eponymous virtual tables".
To use an eponymous virtual table, simple use the 
module name as if it were a table.
Eponymous virtual tables exist in the "main" schema only, so they will
not work if prefixed with a different schema name.

<p>An example of an eponymous virtual table is the [dbstat virtual table].
To use the dbstat virtual table as an eponymous virtual table, 
simply query against the "dbstat"
module name, as if it were an ordinary table.  (Note that SQLite
︙︙