HTTP Query API Support by robsdedude · Pull Request #1319 · neo4j/neo4j-python-driver

robsdedude · 2026-07-07T13:07:10Z

Neo4j servers recently introduced a new HTTP API for querying the database (called Query API): https://neo4j.com/docs/query-api/current/

This PR add support for configuring the driver with a HTTP URL (e.g. https://neo4j.example.com:7474/), which will make the driver run queries and transactions via the HTTP Query API instead of Bolt.

Notes

Please note that:

This feature is in preview (see below).
For the HTTP support 3rd party libraries (currently urllib3 for sync and aiohttp for async) are required. Install pip install neo4j[http] instead of pip install neo4j.
Some features are not supported and likely won't be in the future:
- home database resolution (i.e., user code must always provide an explicit database name for each session created)
- the only supported authentication scheme is basic
Some features are not yet supported:
- Transaction metadata and timeouts are being ignored.
- Some details in the summary (such as neo4j.ResultSummary.server.protocol_info) might be missing or inaccurate.
- Vector types, the UnsupportedType type, and UUIDs cannot be exchanged with the DBMS.
- Notifications and errors have fallback GQL status codes and status information.
- fetch_size has not effect, there is no backpressure mechanism.
- Notification filters (notifications_min_severity, notifications_disabled_categories, notifications_disabled_classifications) have no effect.

Preview

This feature is in preview. This means that it does not follow semver. It might be changed (or in rare cases be removed) at any time without following the normal deprecation cycle.

Depends on:

HTTP/Query API tests neo4j-drivers/testkit#720

Closes: DRIVERS-118

* Server agent string cache bound to driver instance, not interpreter state * Fix using deprecated config of aiohttp * Enable TestKit testing * Docs: mentions that server agent string is computed & cacahed

The HTTP Query API will send `null` for notifications without a position. To make the experience the same between using bolt and HTTP, the driver drops `null` positions via HTTP to make them absent, just like they are via bolt.

StephenCathcart

Other than open questions looks good to me 👍

Signed-off-by: Rouven Bauer <rouven.bauer@neo4j.com>

Fix doc string copy pasta Signed-off-by: Rouven Bauer <rouven.bauer@neo4j.com>

Signed-off-by: Rouven Bauer <rouven.bauer@neo4j.com>

robsdedude added 30 commits November 21, 2025 13:09

WIP

966e97e

Fix lints and mypy errors

38e01e4

Fix existing unit tests

6061617

Implement sync http backend

39907ff

Refactor: reduce sync/async code duplication

8c4068d

Make http dependencies optional

1564c01

Adding tests and fixing found bugs

3697189

Docs and export fixes

22fec6c

Clean-ups

bed28cb

* Server agent string cache bound to driver instance, not interpreter state * Fix using deprecated config of aiohttp * Enable TestKit testing * Docs: mentions that server agent string is computed & cacahed

tmp

e4b2b05

Extend docs on HTTP driver limitations

415857d

Add bearer auth support & fix auth mutability issue

e063c8a

Fix missing impersonation support for transactions

a1f7542

Fix transaction rollback

dea6708

Fix summary counter nodes_created

82d4258

Fix lints

d500355

Fix multiple result streams in single transaction

d7ec594

Fix ServerAgentCache being per-driver instead of per-process

87ff314

Improve summary profile and plan alignment bolt vs http

eb95d5b

Ignore user agent config via HTTP

b23ca1c

Fix position in notification via HTTP

ee9b390

The HTTP Query API will send `null` for notifications without a position. To make the experience the same between using bolt and HTTP, the driver drops `null` positions via HTTP to make them absent, just like they are via bolt.

Verify db names via HTTP Query API

85b5947

Extend documented differences

52b5e65

Add db name restrictions and encoding

30621f8

Fix TestKit backend dependencies

583c88a

Fix error handling and deferral

788e610

Omit empty plans and profiles

190fbb5

Log headers

051a26b

Fix 3D point format for (de)serialization

491f101

Fix duration parsing

e81f281