← Cloudflare D1 / d1 / worker-api

Методы prepared statement

В этой главе описаны различные способы выполнения запроса и получения его результатов после того, как вы подготовили ваш оператор.

Привязывает параметр к prepared statement.

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
  • Переменная, которая добавляется в prepared statement. См. рекомендации ниже.

• D1PreparedStatement: Object
  • A D1PreparedStatement где входной параметр был включён в инструкцию.

• D1 следует соглашение SQLite ↗ для привязки параметров prepared statements. В настоящее время D1 поддерживает только упорядоченную привязку (?NNNN) и Anonymous (?) параметров. В будущем D1 будет поддерживать также именованные параметры.

  Синтаксис	Тип	Описание
  ?NNN	Упорядоченная	Знак вопроса, за которым следует число NNN резервирует место для NNN-й параметр. NNN должен находиться в диапазоне от 1 и SQLITE_MAX_VARIABLE_NUMBER
  ?	Анонимный	Знак вопроса, за которым не следует число, создаёт параметр с номером на единицу больше наибольшего уже назначенного номера параметра. Если из-за этого номер параметра превысит 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-операторы, в которых переменные заданы напрямую в коде. При написании статического оператора вы вручную указываете значение переменной внутри строки оператора.

Пример prepared statement с динамически привязанным значением:

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.

Выполняет подготовленный запрос (или запросы) и возвращает результаты. Возвращаемые результаты включают метаданные.

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"
    }
  ]
}

• results не содержит значения для операций записи, таких как UPDATE, DELETE, или INSERT.
• При использовании TypeScript можно передать параметр типа к D1PreparedStatement::run чтобы вернуть типизированный объект результата.
• D1PreparedStatement::run по функциональности соответствует D1PreparedStatement::all, и это можно рассматривать как псевдоним.
• Вы можете извлекать только ожидаемые результаты оператора, просто возвращая 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({columnNames: true}).

const returnValue = await stmt.raw();

return_value = await stmt.raw()

• columnNames: Object Необязательно
  • Объект типа boolean, который включает имена столбцов в первой строке массива результатов.

• Array: Array
  • Массив массивов. Каждый вложенный массив представляет собой строку.

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"
  ]
]

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 чтобы вернуть типизированный массив результатов.

Выполняет подготовленный запрос (или запросы) и возвращает первую строку результата в виде объекта. Метаданные при этом не возвращаются: сразу возвращается сам объект.

const values = await stmt.first();

values = await stmt.first()

• columnName: String Необязательно
  • Укажите columnName чтобы вернуть значение указанного столбца из первой строки результата запроса.
• Нет.
  • Чтобы получить все столбцы первой строки, не передавайте параметр.

• firstRow: Object Необязательно

  • Объект, содержащий первую строку результата запроса.
  • Возвращаемое значение будет дополнительно отфильтровано до конкретного атрибута, если 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)

11

• Если запрос возвращает строки, но column не существует, то D1PreparedStatement::first выбрасывает D1_ERROR исключение.
• D1PreparedStatement::first не изменяет SQL-запрос. Для повышения производительности рассмотрите возможность добавления LIMIT 1 к вашему запросу.
• При использовании TypeScript можно передать параметр типа к D1PreparedStatement::first чтобы вернуть типизированный объект результата.