プリペアドステートメントのメソッド

この章では、ステートメントを準備したあとに、クエリを実行して結果を取得する各種の方法を説明します。

メソッド

`bind()`

プリペアドステートメントにパラメーターをバインドします。

const someVariable = `Bs Beverages`;
const stmt = env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(someVariable);

some_variable = "Bs Beverages"
stmt = self.env.DB.prepare(
  "SELECT * FROM Customers WHERE CompanyName = ?"
).bind(some_variable)

パラメーター

Variable: string
- プリペアドステートメントに追加する変数です。後述の補足を参照してください。

戻り値

D1PreparedStatement: Object
- 入力パラメーターをステートメントに含めた D1PreparedStatement です。

補足

D1 のプリペアドステートメントのパラメーターバインドは、SQLite の規約 ↗ に従います。現時点で D1 が対応しているのは、順序付き（?NNNN）と無名（?）のパラメーターだけです。将来的には名前付きパラメーターにも対応する予定です。

構文	種類	説明
`?NNN`	順序付き	疑問符のあとに数値 `NNN` を付けると、`NNN` 番目のパラメーターの位置になります。`NNN` は `1` 以上 `SQLITE_MAX_VARIABLE_NUMBER` 以下である必要があります。
`?`	無名	数値の付かない疑問符は、すでに割り当て済みの最大パラメーター番号より 1 大きい番号のパラメーターを作ります。その結果、パラメーター番号が `SQLITE_MAX_VARIABLE_NUMBER` を超える場合はエラーです。この形式は、ほかのデータベースエンジンとの互換性のために用意されています。ただし疑問符の数え間違いが起きやすいため、この形式の使用は推奨しません。シンボリック形式、または上の `?NNN` 形式の使用を推奨します。

パラメーターをバインドするには、.bind メソッドを使います。

順序付きと無名の例:

const stmt = db.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind("");

stmt = db.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind("")

const stmt = db
	.prepare("SELECT * FROM Customers WHERE CompanyName = ? AND CustomerId = ?")
	.bind("Alfreds Futterkiste", 1);

stmt = db.prepare(
"SELECT * FROM Customers WHERE CompanyName = ? AND CustomerId = ?"
).bind("Alfreds Futterkiste", 1)

const stmt = db
	.prepare(
  "SELECT * FROM Customers WHERE CompanyName = ?2 AND CustomerId = ?1"
).bind(1, "Alfreds Futterkiste");

stmt = db.prepare("SELECT * FROM Customers WHERE CompanyName = ?2 AND CustomerId = ?1").bind(1, "Alfreds Futterkiste")

静的ステートメント

D1 API は静的ステートメントにも対応しています。静的ステートメントは、変数をハードコードした SQL 文です。静的ステートメントを書くときは、ステートメント文字列の中に変数を直接書きます。

値を動的にバインドするプリペアドステートメントの例:

const someVariable = `Bs Beverages`;
const stmt = env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(someVariable);
// A variable (someVariable) will replace the placeholder '?' in the query.
// `stmt` is a prepared statement.

some_variable = "Bs Beverages"
stmt = self.env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(some_variable)
# A variable (some_variable) will replace the placeholder '?' in the query.
# `stmt` is a prepared statement.

静的ステートメントの例:

const stmt = env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = 'Bs Beverages'");
// "Bs Beverages" is hard-coded into the query.
// `stmt` is a static statement.

stmt = self.env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = 'Bs Beverages'")
# "Bs Beverages" is hard-coded into the query.
# `stmt` is a static statement.

`run()`

準備したクエリを実行し、結果を返します。戻り値にはメタデータが含まれます。

const returnValue = await stmt.run();

return_value = await stmt.run()

パラメーター

なし。

戻り値

D1Result: Object
- 成功ステータス、meta オブジェクト、クエリ結果を含むオブジェクトの配列を持つオブジェクトです。
- オブジェクトの詳細は D1Result を参照してください。

戻り値の例

const someVariable = `Bs Beverages`;
const stmt = env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(someVariable);
const returnValue = await stmt.run();
return Response.json(returnValue);

from workers import Response

some_variable = "Bs Beverages"
stmt = self.env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(some_variable)
return_value = await stmt.run()
return Response.json(return_value)

{
  "success": true,
  "meta": {
    "served_by": "miniflare.db",
    "duration": 1,
    "changes": 0,
    "last_row_id": 0,
    "changed_db": false,
    "size_after": 8192,
    "rows_read": 4,
    "rows_written": 0
  },
  "results": [
    {
      "CustomerId": 11,
      "CompanyName": "Bs Beverages",
      "ContactName": "Victoria Ashworth"
    },
    {
      "CustomerId": 13,
      "CompanyName": "Bs Beverages",
      "ContactName": "Random Name"
    }
  ]
}

補足

UPDATE、DELETE、INSERT などの書き込み操作では、results は空です。
TypeScript を使う場合は、D1PreparedStatement::run に型パラメーターを渡し、型付きの結果オブジェクトを受け取れます。
D1PreparedStatement::run は機能的に D1PreparedStatement::all と同等で、エイリアスとして扱えます。
期待する結果だけを取り出したい場合は、戻り値オブジェクトの results プロパティを返すだけで足ります。

results だけを返す例

return Response.json(returnValue.results);

from workers import Response

return Response.json(return_value.results)

[
  {
    "CustomerId": 11,
    "CompanyName": "Bs Beverages",
    "ContactName": "Victoria Ashworth"
  },
  {
    "CustomerId": 13,
    "CompanyName": "Bs Beverages",
    "ContactName": "Random Name"
  }
]

`raw()`

準備したクエリを実行し、結果を配列の配列として返します。戻り値にメタデータは含まれません。

デフォルトでは、結果セットに列名は含まれません。結果配列の先頭行として列名を含めるには、.raw({columnNames: true}) を設定します。

const returnValue = await stmt.raw();

return_value = await stmt.raw()

パラメーター

columnNames: Object Optional
- 結果配列の先頭行として列名を含めるかどうかを示す boolean オブジェクトです。

戻り値

Array: Array
- 配列の配列です。各サブ配列が 1 行を表します。

戻り値の例

const someVariable = `Bs Beverages`;
const stmt = env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(someVariable);
const returnValue = await stmt.raw();
return Response.json(returnValue);

from workers import Response

some_variable = "Bs Beverages"
stmt = self.env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(some_variable)
return_value = await stmt.raw()
return Response.json(return_value)

[
  [11, "Bs Beverages",
    "Victoria Ashworth"
  ],
  [13, "Bs Beverages",
    "Random Name"
  ]
]

パラメーター columnNames: true を指定した場合:

const someVariable = `Bs Beverages`;
const stmt = env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(someVariable);
const returnValue = await stmt.raw({columnNames:true});
return Response.json(returnValue)

from workers import Response

some_variable = "Bs Beverages"
stmt = self.env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(some_variable)
return_value = await stmt.raw(columnNames=True)
return Response.json(return_value)

[
  [
    "CustomerId",
    "CompanyName",
    "ContactName"
  ],
  [11, "Bs Beverages",
    "Victoria Ashworth"
  ],
  [13, "Bs Beverages",
    "Random Name"
  ]
]

補足

TypeScript を使う場合は、D1PreparedStatement::raw に型パラメーターを渡し、型付きの結果配列を受け取れます。

`first()`

準備したクエリを実行し、クエリ結果の先頭行をオブジェクトとして返します。メタデータは返しません。オブジェクトを直接返します。

const values = await stmt.first();

values = await stmt.first()

パラメーター

columnName: String Optional
- クエリ結果の先頭行から特定の列の値を返すには、columnName を指定します。
なし。
- パラメーターを渡さないと、先頭行のすべての列を取得します。

戻り値

firstRow: Object Optional
- クエリ結果の先頭行を含むオブジェクトです。
- columnName を指定した場合、戻り値はその属性だけに絞り込まれます。
null: null
- クエリが行を返さない場合です。

戻り値の例

先頭行のすべての列を取得する:

const someVariable = `Bs Beverages`;
const stmt = env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(someVariable);
const returnValue = await stmt.first();
return Response.json(returnValue)

from workers import Response

some_variable = "Bs Beverages"
stmt = self.env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(some_variable)
return_value = await stmt.first()
return Response.json(return_value)

{
  "CustomerId": 11,
  "CompanyName": "Bs Beverages",
  "ContactName": "Victoria Ashworth"
}

先頭行から特定の列を取得する:

const someVariable = `Bs Beverages`;
const stmt = env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(someVariable);
const returnValue = await stmt.first("CustomerId");
return Response.json(returnValue)

from workers import Response

some_variable = "Bs Beverages"
stmt = self.env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(some_variable)
return_value = await stmt.first("CustomerId")
return Response.json(return_value)

補足

クエリが行を返しても column が存在しない場合、D1PreparedStatement::first は D1_ERROR 例外を投げます。
D1PreparedStatement::first は SQL クエリ自体を変更しません。パフォーマンスを上げるには、ステートメントに LIMIT 1 を付けることを検討してください。
TypeScript を使う場合は、D1PreparedStatement::first に型パラメーターを渡し、型付きの結果オブジェクトを受け取れます。