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 -- diff --git a/modules/hello-world/pages/start-using-sdk.adoc b/modules/hello-world/pages/start-using-sdk.adoc index b59f7f3..7008da3 100644 --- a/modules/hello-world/pages/start-using-sdk.adoc +++ b/modules/hello-world/pages/start-using-sdk.adoc @@ -46,20 +46,108 @@ 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. + +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, 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. + + === 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 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: + +`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.results_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..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,8 +190,91 @@ include::devguide:example$python/third_party.py[tag=pyarrow,indent=0] ---- +== Server Asynchronous API (with Python Blocking 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` + +.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.results_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 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. 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] 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] ////