Query D1 Database

d1.database.query(, ) -> SyncSinglePage[QueryResult]

POST/accounts/{account_id}/d1/database/{database_id}/query

Returns the query result as an object.

Security

API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY

API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194

Accepted Permissions (at least one required)

D1 ReadD1 Write

ParametersExpand Collapse

account_id: str

Account identifier tag.

maxLength32

database_id: str

D1 database identifier (UUID).

sql: str

Your SQL query. Supports multiple statements, joined by semicolons, which will be executed as a batch.

params: Optional[SequenceNotStr[str]]

ReturnsExpand Collapse

class QueryResult: …

meta: Optional[Meta]

changed_db: Optional[bool]

Denotes if the database has been altered in some way, like deleting rows.

changes: Optional[float]

Rough indication of how many rows were modified by the query, as provided by SQLite's sqlite3_total_changes().

duration: Optional[float]

The duration of the SQL query execution inside the database. Does not include any network communication.

last_row_id: Optional[float]

The row ID of the last inserted row in a table with an INTEGER PRIMARY KEY as provided by SQLite. Tables created with WITHOUT ROWID do not populate this.

rows_read: Optional[float]

Number of rows read during the SQL query execution, including indices (not all rows are necessarily returned).

rows_written: Optional[float]

Number of rows written during the SQL query execution, including indices.

served_by_colo: Optional[str]

The three letters airport code of the colo that handled the query.

served_by_primary: Optional[bool]

Denotes if the query has been handled by the database primary instance.

served_by_region: Optional[Literal["WNAM", "ENAM", "WEUR", 3 more]]

Region location hint of the database instance that handled the query.

One of the following:

"WNAM"

"ENAM"

"WEUR"

"EEUR"

"APAC"

"OC"

size_after: Optional[float]

Size of the database after the query committed, in bytes.

timings: Optional[MetaTimings]

Various durations for the query.

sql_duration_ms: Optional[float]

The duration of the SQL query execution inside the database. Does not include any network communication.

results: Optional[List[object]]

success: Optional[bool]

Query D1 Database

import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
page = client.d1.database.query(
    database_id="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
    sql="SELECT * FROM myTable WHERE field = ? OR field = ?;",
)
page = page.result[0]
print(page.meta)

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "result": [
    {
      "meta": {
        "changed_db": true,
        "changes": 0,
        "duration": 0,
        "last_row_id": 0,
        "rows_read": 0,
        "rows_written": 0,
        "served_by_colo": "LHR",
        "served_by_primary": true,
        "served_by_region": "EEUR",
        "size_after": 0,
        "timings": {
          "sql_duration_ms": 0
        }
      },
      "results": [
        {}
      ],
      "success": true
    }
  ],
  "success": true
}

Returns Examples

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "result": [
    {
      "meta": {
        "changed_db": true,
        "changes": 0,
        "duration": 0,
        "last_row_id": 0,
        "rows_read": 0,
        "rows_written": 0,
        "served_by_colo": "LHR",
        "served_by_primary": true,
        "served_by_region": "EEUR",
        "size_after": 0,
        "timings": {
          "sql_duration_ms": 0
        }
      },
      "results": [
        {}
      ],
      "success": true
    }
  ],
  "success": true
}