Skip to content
Cloudflare Docs

Prepared statement methods

This chapter documents the various ways you can run and retrieve the results of a query after you have prepared your statement.

Methods

run()

Runs the prepared query (or queries) and returns results. The returned results includes metadata.

const returnValue = await stmt.run();

Parameter

  • None.

Return value

  • D1Result: Object
    • An object containing the success status, a meta object, and an array of objects containing the query results.
    • For more information on the object, refer to D1Result.

Example of return values

 
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);
{
  "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"
    }
  ]
}

Guidance

  • results is empty for write operations such as UPDATE, DELETE, or INSERT.
  • When using TypeScript, you can pass a type parameter to D1PreparedStatement::run to return a typed result object.
  • D1PreparedStatement::run is functionally equivalent to D1PreparedStatement::all, and can be treated as an alias.
  • You can choose to extract only the results you expect from the statement by simply returning the results property of the return object.

Example of returning only the results

 
return Response.json(returnValue.results);
[
  {
    "CustomerId": 11,
    "CompanyName": "Bs Beverages",
    "ContactName": "Victoria Ashworth"
  },
  {
    "CustomerId": 13,
    "CompanyName": "Bs Beverages",
    "ContactName": "Random Name"
  }
]

raw()

Runs the prepared query (or queries), and returns the results as an array of arrays. The returned results do not include metadata.

Column names are not included in the result set by default. To include column names as the first row of the result array, set .raw({columnNames: true}).

const returnValue = await stmt.raw();

Parameters

  • columnNames: Object Optional
    • A boolean object which includes column names as the first row of the result array.

Return values

  • Array: Array
    • An array of arrays. Each sub-array represents a row.

Example of return values

 
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);
[
  [11, "Bs Beverages",
    "Victoria Ashworth"
  ],
  [13, "Bs Beverages",
    "Random Name"
  ]
]

With parameter 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)
[
  [
    "CustomerId",
    "CompanyName",
    "ContactName"
  ],
  [11, "Bs Beverages",
    "Victoria Ashworth"
  ],
  [13, "Bs Beverages",
    "Random Name"
  ]
]

Guidance

first()

Runs the prepared query (or queries), and returns the first row of the query result as an object. This does not return any metadata. Instead, it directly returns the object.

const values = await stmt.first();

Parameters

  • columnName: String Optional
    • Specify a columnName to return a value from a specific column in the first row of the query result.
  • None.
    • Do not pass a parameter to obtain all columns from the first row.

Return values

  • firstRow: Object Optional

    • An object containing the first row of the query result.
    • The return value will be further filtered to a specific attribute if columnName was specified.

  • null: null

    • If the query returns no rows.

Example of return values

Get all the columns from the first row:

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)
{
  "CustomerId": 11,
  "CompanyName": "Bs Beverages",
  "ContactName": "Victoria Ashworth"
}

Get a specific column from the first row:

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)
11

Guidance

Cloudflare DashboardDiscordCommunityLearning CenterSupport Portal
Cookie Settings