From aa2f6fffcc1f59b5aab65e32ba97e8c8bb4de21e Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Thu, 30 Apr 2026 16:11:30 +0100 Subject: [PATCH 1/9] DOC-14204 2.2 anticipation in 1.1 --- modules/hello-world/pages/start-using-sdk.adoc | 5 +++++ modules/project-docs/pages/compatibility.adoc | 9 +++++---- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/modules/hello-world/pages/start-using-sdk.adoc b/modules/hello-world/pages/start-using-sdk.adoc index b59f7f3..4e60ba9 100644 --- a/modules/hello-world/pages/start-using-sdk.adoc +++ b/modules/hello-world/pages/start-using-sdk.adoc @@ -46,6 +46,11 @@ For other installation methods, see the xref:project-docs:sdk-full-installation. == Connecting and Executing a Query +The 1.1 Python SDK also supports an asynchronous (streaming) API update for a forthcoming release of self-managed Enterprise Analytics Server. +The examples below are for the standard API, working with the current 2.0 and 2.1 releases of Enterprise Analytics. +Note, you will be able to use this API with forthcoming 2.x releases of Enterprise Analytics. + + === Synchronous API [source,python] diff --git a/modules/project-docs/pages/compatibility.adoc b/modules/project-docs/pages/compatibility.adoc index fd85e69..f779d5b 100644 --- a/modules/project-docs/pages/compatibility.adoc +++ b/modules/project-docs/pages/compatibility.adoc @@ -42,8 +42,9 @@ include::{sdk_api}@analytics-sdk:shared:partial$network-requirements.adoc[tag=la == Enterprise Analytics Compatibility -This is the initial release of Enterprise Analytics and the Analytics SDKs. -As such, the Analytics SDK is fully compatible with Enterprise Analytics. +The 1.1 releases of the Analytics SDK is fully compatible with currently supported releases of Enterprise Analytics - `1.0` and `1.1`. +The 1.1 Python SDK also supports an asynchronous (streaming) API update for a forthcoming release of self-managed Enterprise Analytics Server. + //// is a fully hosted service, continually updated, and offering the latest version -- @@ -54,7 +55,7 @@ Where older versions of the {name-sdk} pre-date significant new features in Colu - +// add when 2.2 EA Server released //// === API Version @@ -75,7 +76,7 @@ include::{version-common}@analytics-sdk:shared:partial$interface-stability-pars. //// -=== Older SDK Versions +=== Older Analytics SDK Versions include::{version-common}@analytics-sdk:shared:partial$archive.adoc[tag=link] //// From a889347ad6d71000432d735d6473f6027b117dda Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Wed, 6 May 2026 13:35:51 +0100 Subject: [PATCH 2/9] 1.1 verbiage --- .../project-docs/pages/analytics-sdk-release-notes.adoc | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/modules/project-docs/pages/analytics-sdk-release-notes.adoc b/modules/project-docs/pages/analytics-sdk-release-notes.adoc index 20fadea..873efa6 100644 --- a/modules/project-docs/pages/analytics-sdk-release-notes.adoc +++ b/modules/project-docs/pages/analytics-sdk-release-notes.adoc @@ -30,12 +30,15 @@ any changes to expected behavior are noted in the release notes that follow. [[v1.1.0]] -=== Version 1.1.0 (?? 2026) - -This is the first release of the 1.1 Analytics Python SDK dotminor. +=== Version 1.1.0 (?? May 2026) +This is the first release of the 1.1 series Analytics Python SDK. +The 1.1 Analytics SDKs add support for JWT and client certificate authentication, +as well as a new “async” poll-based API that uses request handles to fetch results, +eliminating the need for long-running server connections (compatible with a future release of the Enterprise Analytics server). +https://docs.couchbase.com/sdk-api/analytics-python-client-1.1.0/[API Reference] From 958a0a257baf6273c65d8f6a2ad527dfcbc28f97 Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Wed, 6 May 2026 14:38:23 +0100 Subject: [PATCH 3/9] 2.2 async server example --- .../hello-world/pages/start-using-sdk.adoc | 87 ++++++++++++++++++- .../howtos/pages/sqlpp-queries-with-sdk.adoc | 83 ++++++++++++++++++ 2 files changed, 168 insertions(+), 2 deletions(-) diff --git a/modules/hello-world/pages/start-using-sdk.adoc b/modules/hello-world/pages/start-using-sdk.adoc index 4e60ba9..b299648 100644 --- a/modules/hello-world/pages/start-using-sdk.adoc +++ b/modules/hello-world/pages/start-using-sdk.adoc @@ -47,24 +47,107 @@ For other installation methods, see the xref:project-docs:sdk-full-installation. The 1.1 Python SDK also supports an asynchronous (streaming) API update for a forthcoming release of self-managed Enterprise Analytics Server. + +These releases add support for JWT and client certificate authentication, as well as a new "async" poll-based API that uses request handles to fetch results, eliminating the need for long-running server connections. + + The examples below are for the standard API, working with the current 2.0 and 2.1 releases of Enterprise Analytics. -Note, you will be able to use this API with forthcoming 2.x releases of Enterprise Analytics. +Note, you will still be able to use this API with forthcoming 2.x releases of Enterprise Analytics, in addition to the forthcoming new API. === Synchronous API +.Blocking API Example [source,python] ---- include::devguide:example$python/overview.py[tags=*] ---- -=== Asynchronous (asyncio) API +=== Python Asynchronous API with asyncio +.asyncio Example [source,python] ---- include::devguide:example$python/async_overview.py[tags=*] ---- +=== Server Asynchronous API (with Python blocking API) + +In a future release, the Enterprise Analytics Server will offer an asynchronous request API. +The SDK will send a request, poll for results, and then fetch once the result is available. +The SDK supports each stage of this information flow: + +`cluster.start_query()` → QueryHandle` → `QueryStatus` → `QueryResultsHandle` + +.Server Asynchronous API Example +[source,python] +---- +import logging +import time + +from couchbase_analytics import LOG_DATE_FORMAT, LOG_FORMAT +from couchbase_analytics.cluster import Cluster +from couchbase_analytics.credential import Credential +from couchbase_analytics.query_handle import BlockingQueryHandle, BlockingQueryResultHandle + +# setup logger via basicConfig +logging.basicConfig(format=LOG_FORMAT, datefmt=LOG_DATE_FORMAT, level=logging.DEBUG) + +def wait_for_query_results(handle: BlockingQueryHandle, + delay: float = 2.5, + timeout: int = 120) -> BlockingQueryResultHandle: + current_time = time.monotonic() + deadline = current_time + timeout # seconds + status = None + while True: + try: + status = handle.fetch_status() + if status.is_ready(): + return status.result_handle() + except Exception as e: + # Depending on the use case, you might want to break here or continue retrying. + print(f'Error fetching query results: {e}') + + current_time = time.monotonic() + delay_time = current_time + delay + if deadline < delay_time: + raise TimeoutError(f'Query results not ready within {timeout} seconds.') + else: + if status is not None: + print(f'Query status: {status}') + print(f'Query results not ready yet, sleeping for {delay} seconds...') + + time.sleep(delay) + + + +def main() -> None: + # Update this to your cluster + # IMPORTANT: The appropriate port needs to be specified. The SDK's default ports are 80 (http) and 443 (https). + # If attempting to connect to Capella, the correct ports are most likely to be 8095 (http) and 18095 (https). # noqa: E501 + # Capella example: https://cb.2xg3vwszqgqcrsix.cloud.couchbase.com:18095 + endpoint = 'http://localhost' + username = 'Administrator' + pw = 'password' + # User Input ends here. + + cred = Credential.from_username_and_password(username, pw) + cluster = Cluster.create_instance(endpoint, cred) + statement = 'SELECT VALUE SLEEP("x", 100) FROM RANGE(1, 100) AS id;' + handle = cluster.start_query(statement) + + result_handle = wait_for_query_results(handle, delay=2.5, timeout=60) + res = result_handle.fetch_results() + + for row in res: + print(f'Found row: {row}') + print(f'metadata={res.metadata()}') + result_handle.discard_results() + + +if __name__ == '__main__': + main() +---- === Connection String diff --git a/modules/howtos/pages/sqlpp-queries-with-sdk.adoc b/modules/howtos/pages/sqlpp-queries-with-sdk.adoc index 6560f7e..f2590ef 100644 --- a/modules/howtos/pages/sqlpp-queries-with-sdk.adoc +++ b/modules/howtos/pages/sqlpp-queries-with-sdk.adoc @@ -177,6 +177,89 @@ include::devguide:example$python/third_party.py[tag=pyarrow,indent=0] ---- +== Server Asynchronous API (with Python blocking API) + +In a future release, the Enterprise Analytics Server will offer an asynchronous request API. +The SDK will send a request, poll for results, and then fetch once the result is available. +The SDK supports each stage of this information flow: + +`cluster.start_query()` → QueryHandle` → `QueryStatus` → `QueryResultsHandle` + +.Server Asynchronous API Example +[source,python] +---- +import logging +import time + +from couchbase_analytics import LOG_DATE_FORMAT, LOG_FORMAT +from couchbase_analytics.cluster import Cluster +from couchbase_analytics.credential import Credential +from couchbase_analytics.query_handle import BlockingQueryHandle, BlockingQueryResultHandle + +# setup logger via basicConfig +logging.basicConfig(format=LOG_FORMAT, datefmt=LOG_DATE_FORMAT, level=logging.DEBUG) + +def wait_for_query_results(handle: BlockingQueryHandle, + delay: float = 2.5, + timeout: int = 120) -> BlockingQueryResultHandle: + current_time = time.monotonic() + deadline = current_time + timeout # seconds + status = None + while True: + try: + status = handle.fetch_status() + if status.is_ready(): + return status.result_handle() + except Exception as e: + # Depending on the use case, you might want to break here or continue retrying. + print(f'Error fetching query results: {e}') + + current_time = time.monotonic() + delay_time = current_time + delay + if deadline < delay_time: + raise TimeoutError(f'Query results not ready within {timeout} seconds.') + else: + if status is not None: + print(f'Query status: {status}') + print(f'Query results not ready yet, sleeping for {delay} seconds...') + + time.sleep(delay) + + + +def main() -> None: + # Update this to your cluster + # IMPORTANT: The appropriate port needs to be specified. The SDK's default ports are 80 (http) and 443 (https). + # If attempting to connect to Capella, the correct ports are most likely to be 8095 (http) and 18095 (https). # noqa: E501 + # Capella example: https://cb.2xg3vwszqgqcrsix.cloud.couchbase.com:18095 + endpoint = 'http://localhost' + username = 'Administrator' + pw = 'password' + # User Input ends here. + + cred = Credential.from_username_and_password(username, pw) + cluster = Cluster.create_instance(endpoint, cred) + statement = 'SELECT VALUE SLEEP("x", 100) FROM RANGE(1, 100) AS id;' + handle = cluster.start_query(statement) + + result_handle = wait_for_query_results(handle, delay=2.5, timeout=60) + res = result_handle.fetch_results() + + for row in res: + print(f'Found row: {row}') + print(f'metadata={res.metadata()}') + result_handle.discard_results() + + +if __name__ == '__main__': + main() +---- + + + + + + == Further Information From a0543af3c58f163bc4f8ff24f988c5c24030df72 Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Thu, 7 May 2026 09:56:02 +0100 Subject: [PATCH 4/9] Rename method is_ready to results_ready --- modules/howtos/pages/sqlpp-queries-with-sdk.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/howtos/pages/sqlpp-queries-with-sdk.adoc b/modules/howtos/pages/sqlpp-queries-with-sdk.adoc index f2590ef..926477c 100644 --- a/modules/howtos/pages/sqlpp-queries-with-sdk.adoc +++ b/modules/howtos/pages/sqlpp-queries-with-sdk.adoc @@ -208,7 +208,7 @@ def wait_for_query_results(handle: BlockingQueryHandle, while True: try: status = handle.fetch_status() - if status.is_ready(): + if status.results_ready(): return status.result_handle() except Exception as e: # Depending on the use case, you might want to break here or continue retrying. From a64dfe8f08eaaa49728a187f8fa98502384f19e5 Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Thu, 7 May 2026 09:56:36 +0100 Subject: [PATCH 5/9] Rename status.is_ready() to status.results_ready() --- modules/hello-world/pages/start-using-sdk.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/hello-world/pages/start-using-sdk.adoc b/modules/hello-world/pages/start-using-sdk.adoc index b299648..e655590 100644 --- a/modules/hello-world/pages/start-using-sdk.adoc +++ b/modules/hello-world/pages/start-using-sdk.adoc @@ -102,7 +102,7 @@ def wait_for_query_results(handle: BlockingQueryHandle, while True: try: status = handle.fetch_status() - if status.is_ready(): + if status.results_ready(): return status.result_handle() except Exception as e: # Depending on the use case, you might want to break here or continue retrying. From 1ce621e08fc18b99a13057c886c2fb13c308a517 Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Thu, 7 May 2026 12:31:31 +0100 Subject: [PATCH 6/9] Fix formatting in SDK usage documentation --- modules/hello-world/pages/start-using-sdk.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/hello-world/pages/start-using-sdk.adoc b/modules/hello-world/pages/start-using-sdk.adoc index e655590..fa9bf7b 100644 --- a/modules/hello-world/pages/start-using-sdk.adoc +++ b/modules/hello-world/pages/start-using-sdk.adoc @@ -77,7 +77,7 @@ In a future release, the Enterprise Analytics Server will offer an asynchronous The SDK will send a request, poll for results, and then fetch once the result is available. The SDK supports each stage of this information flow: -`cluster.start_query()` → QueryHandle` → `QueryStatus` → `QueryResultsHandle` +`cluster.start_query()` → `QueryHandle` → `QueryStatus` → `QueryResultsHandle` .Server Asynchronous API Example [source,python] From 09ef768582472a60b3c407ac73c287bd6f397e3f Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Wed, 13 May 2026 14:59:34 +0100 Subject: [PATCH 7/9] Vale tweaks, etc. --- .../hello-world/pages/start-using-sdk.adoc | 6 +++--- .../howtos/pages/sqlpp-queries-with-sdk.adoc | 21 +++++++++++++++---- 2 files changed, 20 insertions(+), 7 deletions(-) diff --git a/modules/hello-world/pages/start-using-sdk.adoc b/modules/hello-world/pages/start-using-sdk.adoc index fa9bf7b..6dfc867 100644 --- a/modules/hello-world/pages/start-using-sdk.adoc +++ b/modules/hello-world/pages/start-using-sdk.adoc @@ -51,7 +51,7 @@ The 1.1 Python SDK also supports an asynchronous (streaming) API update for a fo These releases add support for JWT and client certificate authentication, as well as a new "async" poll-based API that uses request handles to fetch results, eliminating the need for long-running server connections. -The examples below are for the standard API, working with the current 2.0 and 2.1 releases of Enterprise Analytics. +The examples in this are for the standard API, working with the current 2.0 and 2.1 releases of Enterprise Analytics, with an example for the forthcoming API given later in the page. Note, you will still be able to use this API with forthcoming 2.x releases of Enterprise Analytics, in addition to the forthcoming new API. @@ -71,9 +71,9 @@ include::devguide:example$python/overview.py[tags=*] include::devguide:example$python/async_overview.py[tags=*] ---- -=== Server Asynchronous API (with Python blocking API) +== Server Asynchronous API (with Python Blocking API) -In a future release, the Enterprise Analytics Server will offer an asynchronous request API. +In a future release, the Enterprise Analytics Server is expected to offer an asynchronous request API. The SDK will send a request, poll for results, and then fetch once the result is available. The SDK supports each stage of this information flow: diff --git a/modules/howtos/pages/sqlpp-queries-with-sdk.adoc b/modules/howtos/pages/sqlpp-queries-with-sdk.adoc index 926477c..71dda8c 100644 --- a/modules/howtos/pages/sqlpp-queries-with-sdk.adoc +++ b/modules/howtos/pages/sqlpp-queries-with-sdk.adoc @@ -32,6 +32,19 @@ Create a collection to work upon by xref:enterprise-analytics:intro:connecting-t == Querying Your Dataset + +[TIP] +.API Enhancements +==== +The 1.1 Python SDK also supports an asynchronous (streaming) API update for a forthcoming release of self-managed Enterprise Analytics Server. + +These releases add support for JWT and client certificate authentication, as well as a new "async" poll-based API that uses request handles to fetch results, eliminating the need for long-running server connections. + + +The examples in this section are for the standard API, working with the current 2.0 and 2.1 releases of Enterprise Analytics. +Note, you will still be able to use this API with forthcoming 2.x releases of Enterprise Analytics, in addition to the forthcoming new API. +==== + Most queries return more than one result, and you want to iterate over the results: === Scope Level Queries @@ -177,13 +190,13 @@ include::devguide:example$python/third_party.py[tag=pyarrow,indent=0] ---- -== Server Asynchronous API (with Python blocking API) +== Server Asynchronous API (with Python Blocking API) -In a future release, the Enterprise Analytics Server will offer an asynchronous request API. +In a forthcoming release, the Enterprise Analytics Server should offer an asynchronous request API. The SDK will send a request, poll for results, and then fetch once the result is available. The SDK supports each stage of this information flow: -`cluster.start_query()` → QueryHandle` → `QueryStatus` → `QueryResultsHandle` +`cluster.start_query()` → `QueryHandle` → `QueryStatus` → `QueryResultsHandle` .Server Asynchronous API Example [source,python] @@ -264,4 +277,4 @@ if __name__ == '__main__': == Further Information The xref:server:analytics:1_intro.adoc[{sqlpp} for Analytics Reference] -offers a complete guide to the SQL++ language for both of our analytics services, including all of the latest additions. +offers a complete guide to the {sqlpp} language for both of our analytics services, including all of the latest additions. From 1dc3c1f364106a2d7924fa5e1b5fe3ec2d2c36d0 Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Wed, 13 May 2026 14:59:51 +0100 Subject: [PATCH 8/9] Versioning --- modules/hello-world/pages/overview.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/hello-world/pages/overview.adoc b/modules/hello-world/pages/overview.adoc index a48a300..658f8c7 100644 --- a/modules/hello-world/pages/overview.adoc +++ b/modules/hello-world/pages/overview.adoc @@ -4,7 +4,7 @@ :!sectids: -= Python Analytics SDK += Python Analytics SDK {sdk_dot_minor} The Analytics Python SDK allows you to connect to an xref:enterprise-analytics:intro:intro.adoc[Enterprise Analytics] cluster from Python. For connecting to a Couchbase Server Cluster -- self-managed, or Capella Operational -- From 5c4b301058d96aff0701c1ea1db1fa23b50dfecc Mon Sep 17 00:00:00 2001 From: Richard Smedley Date: Wed, 13 May 2026 18:06:51 +0100 Subject: [PATCH 9/9] Fix typo in start-using-sdk.adoc --- modules/hello-world/pages/start-using-sdk.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/hello-world/pages/start-using-sdk.adoc b/modules/hello-world/pages/start-using-sdk.adoc index 6dfc867..7008da3 100644 --- a/modules/hello-world/pages/start-using-sdk.adoc +++ b/modules/hello-world/pages/start-using-sdk.adoc @@ -51,7 +51,7 @@ The 1.1 Python SDK also supports an asynchronous (streaming) API update for a fo These releases add support for JWT and client certificate authentication, as well as a new "async" poll-based API that uses request handles to fetch results, eliminating the need for long-running server connections. -The examples in this are for the standard API, working with the current 2.0 and 2.1 releases of Enterprise Analytics, with an example for the forthcoming API given later in the page. +The examples in this section are for the standard API, working with the current 2.0 and 2.1 releases of Enterprise Analytics, with an example for the forthcoming API given later in the page. Note, you will still be able to use this API with forthcoming 2.x releases of Enterprise Analytics, in addition to the forthcoming new API.