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.

* Skip non-applicable tests * Always specify a database name * Expect preview warning

robsdedude · 2026-07-27T21:13:56Z

 {
  "testkit": {
    "uri": "https://github.com/neo4j-drivers/testkit.git",
-    "ref": "6.x"


TODO: revert once TestKit PR has been merged:

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

StephenCathcart · 2026-08-06T14:27:58Z



+class _Http(_Direct):
+    _default_port = 7687


_Http uses _default_port = 7687, the bolt port, so http://localhost with no port goes there rather than on 7474:

driver = neo4j.GraphDatabase.driver("http://localhost", auth=AUTH) driver.address.port # -> 7687

is that intended, or does https want its own default (7473) as well?

StephenCathcart · 2026-08-06T14:28:01Z

+                    raise
+                if protocol_error or not connection_failed:
+                    raise
+                for request in self._requests:


_CommitRequest never looks constructed anywhere (i think), so this isinstance can't match. the loop also scans the queued _requests, and send_all() has already popped the one in flight (the bolt version looks at self.responses for CommitResponse instead i believe).

i pointed the driver at a stub that drops the connection on the commit POST and answers the retry, and the write went in twice:

write query submitted : 2 time(s) commit attempts : 2 commits dropped : 1 execute_write returned ['Alice']

ServiceUnavailable.is_retryable() is True where IncompleteCommit's is False, so the transaction function replays a commit with an outcome we don't know. am i reading that right? happy to hand over the stub i used to test it

raised this on testkit#720 too, with a test that catches it, so no need for the stub now

StephenCathcart · 2026-08-06T14:28:04Z

+BoundedSemaphore: t.TypeAlias = threading.BoundedSemaphore
+
+
+def acquire_bounded_semaphore(


semaphore.acquire(timeout=...) returns False on timeout rather than raising, and the result isn't kept here, so with max_connection_pool_size=1 i get a second connection out of the sync pool:

conn 0: acquired conn 1: acquired <- over the limit close: ValueError: Semaphore released too many times

the async twin does block, but comes out as a bare TimeoutError rather than ConnectionAcquisitionTimeoutError like the bolt pool. should this be checking the return value, or is this a none issue?

StephenCathcart · 2026-08-06T14:28:06Z

+    async def next_id(self) -> int:
+        async with self._lock:
+            current_id = self._next_id
+            self._next_id = min((self._next_id + 1) % IdGenerator._MAX, 1)


min keeps this at 1 forever, so every http connection logged for me as [#0001]. did you mean max, to skip 0 on wrap?

Suggested change

self._next_id = min((self._next_id + 1) % IdGenerator._MAX, 1)

self._next_id = max((self._next_id + 1) % IdGenerator._MAX, 1)

StephenCathcart · 2026-08-06T14:28:08Z

+@dataclasses.dataclass(slots=True, frozen=True, kw_only=True)
+class HTTPServerInfo:
+    neo4j_version: str
+    parsed_neo4j_version: tuple[int, int] | None = dataclasses.field(


i've got a half-memory of a call about parsing the server version and rejecting the older ones that send values as a flat list rather than a list of records, so users get a clear message instead of a parse error. parsed_neo4j_version is computed here but i couldn't find anything reading it, so i may have the wrong end of this.

a stub advertising 5.19.0 with the flat shape gives:

QueryApiHttpError: protocol error: expected list, got: 1

and that class's docstring points people at filing a driver bug. can't recall if I'm remembering this correctly, and whether it still needs changed?

StephenCathcart · 2026-08-06T14:28:11Z

-Async Driver Construction
-=========================
+AsyncDriver Construction
+========================


async_api.rst doesn't look like it picked up the http changes that api.rst got: no http/https in the valid-URI list or the scheme table, no AsyncHttpDriver autoclass section, and line 454 still reads "the URI scheme is bolt:// or neo4j://". AsyncHttpDriver is exported and carries the whole "Unavailable Features" docstring, so i think none of it renders for async users. are the async docs to do at a later time?

StephenCathcart · 2026-08-06T14:28:30Z

+        * :attr:`.ResultSummary.result_available_after` and
+          :attr:`.ResultSummary.result_consumed_after` will always be
+          :data:`None` because this information is not provided by the server.
+          TODO: check whether None or 0!!
+        * :attr:`.ServerInfo.agent` is being computed from the DBMS's
+          advertised version. Further, it is being cached to reduce
+          round-trips and overloading the DBMS's HTTP endpoints.
+        * :attr:`.ResultSummary.query_type` will always be :data:`None`.
+
+    * Transmitting and receiving :class:`Vector` values is currently not
+      supported.
+
+    * The only supported auth scheme (see :ref:`auth-ref`) is ``"basic"`` and
+      ``"bearer"``.


Suggested change

* :attr:`.ResultSummary.result_available_after` and

:attr:`.ResultSummary.result_consumed_after` will always be

:data:`None` because this information is not provided by the server.

TODO: check whether None or 0!!

* :attr:`.ServerInfo.agent` is being computed from the DBMS's

advertised version. Further, it is being cached to reduce

round-trips and overloading the DBMS's HTTP endpoints.

* :attr:`.ResultSummary.query_type` will always be :data:`None`.

* Transmitting and receiving :class:`Vector` values is currently not

supported.

* The only supported auth scheme (see :ref:`auth-ref`) is ``"basic"`` and

``"bearer"``.

* :attr:`.ResultSummary.result_available_after` and

:attr:`.ResultSummary.result_consumed_after` will always be

:data:`None` because this information is not provided by the server.

* :attr:`.ServerInfo.agent` is being computed from the DBMS's

advertised version. Further, it is being cached to reduce

round-trips and overloading the DBMS's HTTP endpoints.

* :attr:`.ResultSummary.query_type` will always be :data:`None`.

* Transmitting and receiving :class:`Vector` values is currently not

supported.

* The only supported auth schemes (see :ref:`auth-ref`) are ``"basic"`` and

``"bearer"``.

is -> are, and removed the TODO as I "think" it's None - worth checking

StephenCathcart · 2026-08-06T14:28:33Z

+    @property
+    @abc.abstractmethod
+    def supports_notification_filtering(self) -> bool:
+        """Whether the connection version supports re-authentication."""


Suggested change

"""Whether the connection version supports re-authentication."""

"""Whether the connection version supports notification filtering."""

StephenCathcart · 2026-08-06T14:28:35Z

+    A string value must be provided connected via
+    ``http://`` or ``https://`` scheme.


Suggested change

A string value must be provided connected via

``http://`` or ``https://`` scheme.

A string value must be provided when connected via

``http://`` or ``https://`` scheme.

StephenCathcart · 2026-08-06T14:28:37Z

+                return await self._fetch_unguarded(query_api)
+            except Exception as e:
+                log.warning(
+                    "[#%04X]  _: Failed to fetch  server info: %r",


Suggested change

"[#%04X] _: Failed to fetch server info: %r",

"[#%04X] _: Failed to fetch server info: %r",

StephenCathcart · 2026-08-06T14:28:39Z

+    def _compute_repr(self) -> str:
+        fields_repr = (
+            f"{key!r}: {value!r}" for key, value in self._iter_sanintized()
+        )
+        return f"{{{', '.join(fields_repr)}}}"
+
+    def _iter_sanintized(self) -> t.Generator[tuple[str, str]]:


Suggested change

def _compute_repr(self) -> str:

fields_repr = (

f"{key!r}: {value!r}" for key, value in self._iter_sanintized()

)

return f"{{{', '.join(fields_repr)}}}"

def _iter_sanintized(self) -> t.Generator[tuple[str, str]]:

def _compute_repr(self) -> str:

fields_repr = (

f"{key!r}: {value!r}" for key, value in self._iter_sanitized()

)

return f"{{{', '.join(fields_repr)}}}"

def _iter_sanitized(self) -> t.Generator[tuple[str, str]]:

StephenCathcart · 2026-08-06T14:28:42Z

+.. _http-driver-ref:
+
+HttpDriver
+===========


Suggested change

===========

==========

StephenCathcart

Other than open questions looks good to me 👍

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

robsdedude added 15 commits July 8, 2026 09:24

tmp: point testkit to query-api branch

2b39113

Avoid aiohttp ResourceWarning

745a0f3

Fix unit tests with pandas without pyarrow

ac48291

Fix qid tracking and optimization

05b9ded

Fix duplicated test fixtures

322a01e

ITs: expect preview warning creating http(s) drivers

e15077a

fixup! Fix duplicated test fixtures

d9ba5ee

Fix missing attribute error in logging call

ce577b2

Improve error handling and re-writing

71bde3d

ITs: handle HTTP/Query API

e161410

* Skip non-applicable tests * Always specify a database name * Expect preview warning

fixup! ITs: handle HTTP/Query API

8a361e6

fixup! Fix missing attribute error in logging call

e65fbb9

fixup! ITs: handle HTTP/Query API

1a8738c

Make mypy happy

feb77fa

Merge branch '6.x' into feat/query-api

483612e

robsdedude commented Jul 27, 2026

View reviewed changes

robsdedude requested a review from StephenCathcart July 29, 2026 10:34

StephenCathcart reviewed Aug 6, 2026

View reviewed changes

StephenCathcart approved these changes Aug 6, 2026

View reviewed changes

		BoundedSemaphore: t.TypeAlias = threading.BoundedSemaphore


		def acquire_bounded_semaphore(

	self._next_id = min((self._next_id + 1) % IdGenerator._MAX, 1)
	self._next_id = max((self._next_id + 1) % IdGenerator._MAX, 1)

	"""Whether the connection version supports re-authentication."""
	"""Whether the connection version supports notification filtering."""

		A string value must be provided connected via
		``http://`` or ``https://`` scheme.

	"[#%04X] _: Failed to fetch server info: %r",
	"[#%04X] _: Failed to fetch server info: %r",

Uh oh!

Conversation

robsdedude commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Notes

Preview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

StephenCathcart Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

StephenCathcart Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

StephenCathcart Aug 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

StephenCathcart Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

StephenCathcart Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

StephenCathcart Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

StephenCathcart Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

StephenCathcart left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

robsdedude commented Jul 7, 2026 •

edited

Loading

StephenCathcart Aug 6, 2026 •

edited

Loading

StephenCathcart Aug 6, 2026 •

edited

Loading

StephenCathcart Aug 7, 2026 •

edited

Loading

StephenCathcart Aug 6, 2026 •

edited

Loading

StephenCathcart Aug 6, 2026 •

edited

Loading

StephenCathcart Aug 6, 2026 •

edited

Loading

StephenCathcart Aug 6, 2026 •

edited

Loading