查看“Better-sqlite3 class Statement”的源代码


<span id="runbindparameters---object"></span>
=== .run([''…bindParameters'']) -&gt; ''object'' ===

执行预处理语句。当执行完成时返回一个描述所做的更改的<code>info</code>对象。<code>info</code>对象有两个属性：

* <code>info.changes</code>: 此操作插入、更新或删除的总行数。由外键操作或触发程序所做的更改不计数。
* <code>info.lastInsertRowid</code>: 最后插入到数据库中的行的rowid（忽略由触发程序引起的）。如果当前语句没有向数据库插入任何行，则此数字应完全忽略。

<br>

如果语句执行失败，将抛出错误。

<br>

您可以指定绑定参数，这些参数仅在给定执行中绑定。

<syntaxhighlight lang="js">const stmt = db.prepare('INSERT INTO cats (name, age) VALUES (?, ?)');
const info = stmt.run('Joey', 2);

console.log(info.changes); // => 1</syntaxhighlight>
<br>

<span id="getbindparameters---row"></span>
=== .get([''…bindParameters'']) -&gt; ''row'' ===

**(仅在返回数据的语句上)*

执行预处理语句。当执行完成时返回一个表示查询结果的第一行的对象。对象的键表示列名。

如果语句成功但未找到数据，则返回<code>undefined</code>。如果语句执行失败，将抛出错误。

<br>

您可以指定绑定参数，这些参数仅在给定执行中绑定。

<syntaxhighlight lang="js">const stmt = db.prepare('SELECT age FROM cats WHERE name = ?');
const cat = stmt.get('Joey');

console.log(cat.age); // => 2</syntaxhighlight>
<br>

<span id="allbindparameters---array-of-rows"></span>
=== .all([''…bindParameters'']) -&gt; ''array of rows'' ===

**(仅在返回数据的语句上)*

类似于<code>.get()</code>，但检索所有匹配的行而不是仅检索一行。返回值是行对象的数组。

<br>

如果没有找到行，数组将为空。如果语句执行失败，将抛出错误。

您可以指定绑定参数，这些参数仅在给定执行中绑定。

<syntaxhighlight lang="js">const stmt = db.prepare('SELECT * FROM cats WHERE name = ?');
const cats = stmt.all('Joey');

console.log(cats.length); // => 1</syntaxhighlight>
<br>

<span id="iteratebindparameters---iterator"></span>
=== .iterate([''…bindParameters'']) -&gt; ''iterator'' ===

**(仅在返回数据的语句上)*

类似于<code>.all()</code>，但返回的迭代器不是将所有行一起返回，而是逐个返回行。如果您无论如何都要检索每一行，<code>.all()</code>将性能更好。

<br>

如果语句执行失败，将抛出错误并关闭迭代器。

您可以指定绑定参数，这些参数仅在给定执行中绑定。

<syntaxhighlight lang="js">const stmt = db.prepare('SELECT * FROM cats');

for (const cat of stmt.iterate()) {
  if (cat.name === 'Joey') {
    console.log('found him!');
    break;
  }
}</syntaxhighlight>
<br>

<span id="plucktogglestate---this"></span>
=== .pluck([toggleState]) -&gt; ''this'' ===

**(仅在返回数据的语句上)*

导致预处理语句只返回检索的任何行的第一列的值，而不是整个行对象。

<br>

您可以根据需要切换此选项：

<syntaxhighlight lang="js">stmt.pluck(); // plucking ON
stmt.pluck(true); // plucking ON
stmt.pluck(false); // plucking OFF</syntaxhighlight>
<blockquote>当启用提取时，扩展和原始模式被关闭（它们是互斥的选项）。
</blockquote>
<br>

<span id="rawtogglestate---this"></span>
=== .raw([toggleState]) -&gt; ''this'' ===

**(仅在返回数据的语句上)*

使预处理语句将行作为数组返回，而不是对象。这主要用于在检索大量行时进行性能优化。可以通过使用<code>.columns()</code>方法恢复列名。

<br>

您可以随意切换此模式：

<syntaxhighlight lang="js">stmt.raw(); // raw模式开启
stmt.raw(true); // raw模式开启
stmt.raw(false); // raw模式关闭</syntaxhighlight>
<blockquote>当raw模式开启时，plucking和expansion被关闭（它们是互斥的选项）。
</blockquote>
<br>

<span id="columns---array-of-objects"></span>
=== .columns() -&gt; ''array of objects'' ===

**(仅在返回数据的语句上)*

此方法主要用于与raw模式结合使用。它返回一个对象数组，其中每个对象描述预处理语句的结果列。每个对象具有以下属性：

* <code>.name</code>: 结果列的名称（或别名）。
* <code>.column</code>: 源表列的名称，如果它是表达式或子查询，则为<code>null</code>。
* <code>.table</code>: 源表的名称，如果它是表达式或子查询，则为<code>null</code>。
* <code>.database</code>: 源数据库的名称，如果它是表达式或子查询，则为<code>null</code>。
* <code>.type</code>: [https://www.sqlite.org/datatype3.html#determination_of_column_affinity 声明类型]的名称，如果它是表达式或子查询，则为<code>null</code>。

<br>

<syntaxhighlight lang="js">const fs = require('fs');

function* toRows(stmt) {
  yield stmt.columns().map(column => column.name);
  yield* stmt.raw().iterate();
}

function writeToCSV(filename, stmt) {
  return new Promise((resolve, reject) => {
    const stream = fs.createWriteStream(filename);
    for (const row of toRows(stmt)) {
      stream.write(row.join(',') + '\n');
    }
    stream.on('error', reject);
    stream.end(resolve);
  });
}</syntaxhighlight>
<blockquote>当表的模式发生更改时，现有的预处理语句可能开始返回不同的结果列。然而，这些更改不会通过此方法反映，直到预处理语句重新执行。因此，最好在调用<code>.columns()</code>之后调用<code>.get()</code>、<code>.all()</code>或<code>.iterate()</code>。
</blockquote>
<br>

<span id="bindbindparameters---this"></span>
=== .bind([''…bindParameters'']) -&gt; ''this'' ===

将给定的参数绑定到语句 ''永久地''。与在执行时绑定参数不同，这些参数将永久地绑定到预处理语句的整个生命周期。

在此类语句的参数绑定后，您可能不再为其提供执行特定的（临时）绑定参数。

<br>

此方法主要用于在需要多次使用相同的预处理语句和绑定参数时进行性能优化。

<syntaxhighlight lang="js">const stmt = db.prepare('SELECT * FROM cats WHERE name = ?').bind('Joey');
const cat = stmt.get();

console.log(cat.name); // => "Joey"</syntaxhighlight>
<br>

<span id="属性-1"></span>
== 属性 ==

'''.database -&gt; ''object''''' - 父数据库对象。

'''.source -&gt; ''string''''' - 用于创建预处理语句的源字符串。

'''.reader -&gt; ''boolean''''' - 预处理语句是否返回数据。

'''.readonly -&gt; ''boolean''''' - 预处理语句是否为只读，即它不会更改数据库（注意，[https://www.sqlite.org/c3ref/stmt_readonly.html SQL函数可能仍然间接地更改数据库]作为副作用，即使<code>.readonly</code>属性为<code>true</code>）。

'''.busy -&gt; ''boolean''''' - 预处理语句是否通过<code>.iterate()</code>方法正在执行查询。

<br>