Debian Codegraph @

www/carray.html

raw
1 <!DOCTYPE html>
2 <html><head>
3 <meta name="viewport" content="width=device-width, initial-scale=1.0">
4 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
5 <link href="sqlite.css" rel="stylesheet">
6 <title>The Carray() Table-Valued Function</title>
7 <!-- path= -->
8 </head>
9 <body>
10 <div class=nosearch>
11 <a href="index.html">
12 <img class="logo" src="images/sqlite370_banner.svg" alt="SQLite" border="0">
13 </a>
14 <div><!-- IE hack to prevent disappearing logo --></div>
15 <div class="tagline desktoponly">
16 Small. Fast. Reliable.<br>Choose any three.
17 </div>
18 <div class="menu mainmenu">
19 <ul>
20 <li><a href="index.html">Home</a>
21 <li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
22 <li class='wideonly'><a href='about.html'>About</a>
23 <li class='desktoponly'><a href="docs.html">Documentation</a>
24 <li class='desktoponly'><a href="download.html">Download</a>
25 <li class='wideonly'><a href='copyright.html'>License</a>
26 <li class='desktoponly'><a href="support.html">Support</a>
27 <li class='desktoponly'><a href="prosupport.html">Purchase</a>
28 <li class='search' id='search_menubutton'>
29 <a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
30 </ul>
31 </div>
32 <div class="menu submenu" id="submenu">
33 <ul>
34 <li><a href='about.html'>About</a>
35 <li><a href='docs.html'>Documentation</a>
36 <li><a href='download.html'>Download</a>
37 <li><a href='support.html'>Support</a>
38 <li><a href='prosupport.html'>Purchase</a>
39 </ul>
40 </div>
41 <div class="searchmenu" id="searchmenu">
42 <form method="GET" action="search">
43 <select name="s" id="searchtype">
44 <option value="d">Search Documentation</option>
45 <option value="c">Search Changelog</option>
46 </select>
47 <input type="text" name="q" id="searchbox" value="">
48 <input type="submit" value="Go">
49 </form>
50 </div>
51 </div>
52 <script>
53 function toggle_div(nm) {
54 var w = document.getElementById(nm);
55 if( w.style.display=="block" ){
56 w.style.display = "none";
57 }else{
58 w.style.display = "block";
59 }
60 }
61 function toggle_search() {
62 var w = document.getElementById("searchmenu");
63 if( w.style.display=="block" ){
64 w.style.display = "none";
65 } else {
66 w.style.display = "block";
67 setTimeout(function(){
68 document.getElementById("searchbox").focus()
69 }, 30);
70 }
71 }
72 function div_off(nm){document.getElementById(nm).style.display="none";}
73 window.onbeforeunload = function(e){div_off("submenu");}
74 /* Disable the Search feature if we are not operating from CGI, since */
75 /* Search is accomplished using CGI and will not work without it. */
76 if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
77 document.getElementById("search_menubutton").style.display = "none";
78 }
79 /* Used by the Hide/Show button beside syntax diagrams, to toggle the */
80 function hideorshow(btn,obj){
81 var x = document.getElementById(obj);
82 var b = document.getElementById(btn);
83 if( x.style.display!='none' ){
84 x.style.display = 'none';
85 b.innerHTML='show';
86 }else{
87 x.style.display = '';
88 b.innerHTML='hide';
89 }
90 return false;
91 }
92 var antiRobot = 0;
93 function antiRobotGo(){
94 if( antiRobot!=3 ) return;
95 antiRobot = 7;
96 var j = document.getElementById("mtimelink");
97 if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
98 }
99 function antiRobotDefense(){
100 document.body.onmousedown=function(){
101 antiRobot |= 2;
102 antiRobotGo();
103 document.body.onmousedown=null;
104 }
105 document.body.onmousemove=function(){
106 antiRobot |= 2;
107 antiRobotGo();
108 document.body.onmousemove=null;
109 }
110 setTimeout(function(){
111 antiRobot |= 1;
112 antiRobotGo();
113 }, 100)
114 antiRobotGo();
115 }
116 antiRobotDefense();
117 </script>
118 <div class=fancy>
119 <div class=nosearch>
120 <div class="fancy_title">
121 The Carray() Table-Valued Function
122 </div>
123 </div>
124
125
126
127
128 <h1 id="overview"><span>1. </span>Overview</h1>
129
130 <p>Carray() is a <a href="vtab.html#tabfunc2">table-valued function</a> with a single column (named
131 "value") and zero or more rows.
132 The "value" of each row in the carray() is taken from a C-language array
133 supplied by the application via <a href="c3ref/bind_blob.html">parameter binding</a>.
134 In this way, the carray() function provides a convenient mechanism to
135 bind C-language arrays to SQL queries.
136
137 </p><h1 id="availability"><span>2. </span>Availability</h1>
138
139 <p>Since SQLite version 3.51.0 (2025-11-04), the carray() extension
140 has been built into <a href="amalgamation.html">the amalgamation</a>, though it is disabled by default
141 and does not function unless SQLite is compiled with
142 <a href="compile.html#enable_carray">-DSQLITE_ENABLE_CARRAY</a>. Prior to version 3.51.0, carray() was in a
143 separate source file that needed to be compiled independently and then
144 added to SQLite as a <a href="loadext.html">loadable extension</a>.
145
146 </p><p>The carray() function was first added to SQLite in version 3.14
147 (2016-08-08). The sqlite3_carray_bind() interface and the
148 single-argument variant of carray() was added in SQLite version 3.34.0
149 (2020-12-01). The ability to bind an array of <tt>struct iovec</tt>
150 objects that are interpreted as BLOBs was added in SQLite version 3.41.0
151 (2023-02-21).
152
153 </p><h1 id="details"><span>3. </span>Details</h1>
154
155 <p>The carray() function takes one, two, or three arguments.
156 The one-argument variant is recommended.
157
158 <a name="onearg"></a>
159
160 </p><h2 id="single_argument_carray"><span>3.1. </span>Single-Argument CARRAY</h2>
161
162 <p>The single-argument form of carray() requires a special C-language
163 interface named "sqlite3_carray_bind()" in order to attach values:
164
165 </p><blockquote><pre>
166 int sqlite3_carray_bind(
167 sqlite3_stmt *pStmt, /* Statement containing the CARRAY */
168 int idx, /* Parameter number for CARRAY argument */
169 void *aData, /* Data array */
170 int nData, /* Number of entries in the array */
171 int mFlags, /* Datatype flag */
172 void (*xDestroy)(void*) /* Destructor for aData */
173 );
174 </pre></blockquote>
175
176 <p>The mFlags parameter to sqlite3_carray_bind() must be one of:
177
178 </p><blockquote><pre>
179 #define SQLITE_CARRAY_INT32 0
180 #define SQLITE_CARRAY_INT64 1
181 #define SQLITE_CARRAY_DOUBLE 2
182 #define SQLITE_CARRAY_TEXT 3
183 #define SQLITE_CARRAY_BLOB 4
184 </pre></blockquote>
185
186 <p>The SQLITE_CARRAY_INT32 type means that the array is an array of "int".
187 The SQLITE_CARRAY_INT64 means the array is an array of "<a href="c3ref/int64.html">sqlite3_int64</a>".
188 The SQLITE_CARRAY_DOUBLE argument means the array is an array of "double".
189 The SQLITE_CARRAY_TEXT means the array is an array of "char*" where each
190 element of the array is either a NULL pointer or a pointer to a
191 zero-terminated string.
192
193 </p><p>The SQLITE_CARRAY_BLOB argument means that the array is an array of
194 "struct iovec" objects.
195 The 'struct iovec' type is a standard Posix data
196 structure, normally declared using "<tt>#include &lt;sys/uio.h&gt;</tt>".
197 The format is:
198
199 </p><blockquote><pre>
200 struct iovec {
201 void *iov_base; /* Starting address */
202 size_t iov_len; /* Number of bytes to transfer */
203 };
204 </pre></blockquote>
205
206 <p>Higher order bits of the mFlags parameter must all be zero for now,
207 though they may be used in future enhancements.
208
209 </p><p>The xDestroy argument to sqlite3_carray_bind() routine is a pointer
210 to a function that frees the input array. SQLite will invoke this
211 function after it has finished with the data. The xDestroy argument
212 may optionally be one of the following constants defined in
213 "sqlite3.h":
214
215 </p><ul>
216 <li><p>
217 <a href="c3ref/c_static.html">SQLITE_STATIC</a> &rarr; This means that the application that invokes
218 sqlite3_carray_bind() maintains ownership of the data array and that
219 the application promises SQLite that it will not change or deallocate
220 the data until after the prepared statement is finalized.
221
222 </p></li><li><p>
223 <a href="c3ref/c_static.html">SQLITE_TRANSIENT</a> &rarr; This special value instructs SQLite to make
224 its own private copy of the data before the
225 sqlite3_carray_bind() interface returns.
226 </p></li></ul>
227
228 <a name="twoarg"></a>
229
230 <h2 id="multi_argument_carray"><span>3.2. </span>Multi-Argument CARRAY</h2>
231
232 <p>The original carray() design used two or three arguments. This
233 method is still supported for backwards compatibility, however new
234 applications are encouraged to use the single-argument carray() design
235 described above.
236
237 </p><p>For the two- and three-argument versions of carray(),
238 the first argument is a pointer to an array. Since pointer values cannot
239 be specified directly in SQL, the first argument must be a <a href="lang_expr.html#varparam">parameter</a> that
240 is bound to a pointer value using the <a href="c3ref/bind_blob.html">sqlite3_bind_pointer()</a> interface
241 using a pointer-type of "carray".
242 The second argument is the number of elements in the array. The optional
243 third argument is a string that determines the datatype of the elements
244 in the C-language array. Allowed values for the third argument are:
245
246 </p><ol>
247 <li> 'int32'
248 </li><li> 'int64'
249 </li><li> 'double'
250 </li><li> 'char*'
251 </li><li> 'struct iovec'
252 </li></ol>
253
254 <p>The default datatype is 'int32'. The 'int32' datatype is assumed if
255 the carray() function has only two arguments.
256
257 </p><h1 id="usage"><span>4. </span>Usage</h1>
258
259 <p>The carray() function can be used in the FROM clause of a query.
260 For example, to query two entries from the OBJ table using rowids
261 taken from a C-language array at address $PTR.
262
263 </p><div class="codeblock"><pre>SELECT obj.* FROM obj, carray($PTR) AS x
264 WHERE obj.rowid=x.value;
265 </pre></div>
266
267 <p>This query gives the same result:
268
269 </p><div class="codeblock"><pre>SELECT * FROM obj WHERE rowid IN carray($PTR);
270 </pre></div>
271 <p align="center"><small><i>This page was last updated on 2026-01-26 15:45:07Z </small></i></p>
272