NCO-57: Async Analytics Query

src/Couchbase.Analytics/Async/QueryHandle.cs

@@ -39,14 +39,14 @@ public class QueryHandle
     internal AsyncQueryMetrics? Metrics { get; }
 
     /// <summary>
-    /// The query handle string used to poll for the result handle.
+    /// The query handle string used to poll for the query status.
     /// </summary>
-    public string Handle { get; }
+    internal string Handle { get; }
 
     /// <summary>
     /// The request ID assigned by the server when the query was submitted.
     /// </summary>
-    public string RequestId { get; }
+    internal string RequestId { get; }
 
     internal QueryHandle(string handle, string requestId, JsonElement root, IAnalyticsService analyticsService)
     {
@@ -67,25 +67,25 @@ internal QueryHandle(string handle, string requestId, JsonElement root, IAnalyti
     }
 
     /// <summary>
-    /// Fetches the result handle of the asynchronous query from the server.
+    /// Fetches the current status of the asynchronous query from the server.
     /// </summary>
-    /// <param name="options">Options for fetching the result handle.</param>
+    /// <param name="options">Options for fetching the status.</param>
     /// <param name="cancellationToken">A cancellation token.</param>
-    /// <returns>A <see cref="QueryResultHandle"/> if results are ready, otherwise null.</returns>
-    public Task<QueryResultHandle?> FetchResultHandleAsync(FetchResultHandleOptions? options = null, CancellationToken cancellationToken = default)
+    /// <returns>A <see cref="QueryStatus"/> representing the current state of the query.</returns>
+    public Task<QueryStatus> FetchStatusAsync(FetchStatusOptions? options = null, CancellationToken cancellationToken = default)
     {
-        options ??= new FetchResultHandleOptions();
-        return _analyticsService.FetchResultHandleAsync(this, options, cancellationToken);
+        options ??= new FetchStatusOptions();
+        return _analyticsService.FetchStatusAsync(this, options, cancellationToken);
     }
 
     /// <summary>
-    /// Fetches the result handle of the asynchronous query from the server.
+    /// Fetches the current status of the asynchronous query from the server.
     /// </summary>
-    public Task<QueryResultHandle?> FetchResultHandleAsync(Func<FetchResultHandleOptions, FetchResultHandleOptions> options, CancellationToken cancellationToken = default)
+    public Task<QueryStatus> FetchStatusAsync(Func<FetchStatusOptions, FetchStatusOptions> options, CancellationToken cancellationToken = default)
     {
-        var fetchOptions = new FetchResultHandleOptions();
+        var fetchOptions = new FetchStatusOptions();
         fetchOptions = options.Invoke(fetchOptions);
-        return FetchResultHandleAsync(fetchOptions, cancellationToken);
+        return FetchStatusAsync(fetchOptions, cancellationToken);
     }
 
     /// <summary>

src/Couchbase.Analytics/Async/QueryStatus.cs

@@ -0,0 +1,170 @@
+#region License
+/* ************************************************************
+ *
+ *    @author Couchbase <info@couchbase.com>
+ *    @copyright 2025 Couchbase, Inc.
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ *
+ * ************************************************************/
+#endregion
+
+using System.Text.Json;
+using Couchbase.AnalyticsClient.Internal;
+using Couchbase.AnalyticsClient.Query;
+
+namespace Couchbase.AnalyticsClient.Async;
+
+/// <summary>
+/// Represents the status of a server-side asynchronous query.
+/// Obtained from <see cref="QueryHandle.FetchStatusAsync"/>.
+/// </summary>
+public class QueryStatus
+{
+    private readonly string? _resultHandlePath;
+    private readonly string _requestId;
+    private readonly JsonElement _root;
+    private readonly IAnalyticsService _analyticsService;
+
+    internal string? Status { get; }
+
+    internal AsyncQueryMetrics? Metrics { get; }
+
+    internal int? ResultCount { get; }
+
+    internal bool? ResultSetOrdered { get; }
+
+    internal string? CreatedAt { get; }
+
+    internal int PartitionCount { get; }
+
+    /// <summary>
+    /// Returns <c>true</c> if and only if the server response provides a handle
+    /// for the SDK to retrieve the query results. Otherwise returns <c>false</c>.
+    /// This property does not perform network calls.
+    /// </summary>
+    public bool ResultsReady { get; }
+
+    internal QueryStatus(string requestId, JsonElement root, IAnalyticsService analyticsService)
+    {
+        _requestId = requestId ?? throw new ArgumentNullException(nameof(requestId));
+        _analyticsService = analyticsService ?? throw new ArgumentNullException(nameof(analyticsService));
+
+        if (root.ValueKind is JsonValueKind.Undefined or JsonValueKind.Null)
+        {
+            throw new ArgumentException("The JSON response element must not be empty or null.", nameof(root));
+        }
+
+        _root = root;
+
+        // ── Core fields ──
+        Status = root.TryGetProperty("status", out var statusProp) ? statusProp.GetString() : null;
+
+        if (root.TryGetProperty("metrics", out var metricsElement))
+        {
+            Metrics = JsonSerializer.Deserialize<AsyncQueryMetrics>(metricsElement.GetRawText());
+        }
+
+        // ResultsReady is true when the server provides a result handle path
+        _resultHandlePath = root.TryGetProperty("handle", out var handleProp) ? handleProp.GetString() : null;
+        ResultsReady = !string.IsNullOrWhiteSpace(_resultHandlePath);
+
+        // ── Optional diagnostic fields (may be absent depending on server version or query state) ──
+        if (root.TryGetProperty("resultCount", out var resultCountProp) && resultCountProp.TryGetInt32(out var resultCount))
+        {
+            ResultCount = resultCount;
+        }
+
+        if (root.TryGetProperty("resultSetOrdered", out var orderedProp) && orderedProp.ValueKind is JsonValueKind.True or JsonValueKind.False)
+        {
+            ResultSetOrdered = orderedProp.GetBoolean();
+        }
+
+        CreatedAt = root.TryGetProperty("createdAt", out var createdProp) ? createdProp.GetString() : null;
+
+        if (root.TryGetProperty("partitions", out var partProp) && partProp.ValueKind == JsonValueKind.Array)
+        {
+            PartitionCount = partProp.GetArrayLength();
+        }
+    }
+
+    /// <summary>
+    /// Returns a new <see cref="QueryResultHandle"/> instance.
+    /// This method does not perform network calls.
+    /// </summary>
+    /// <returns>A <see cref="QueryResultHandle"/> that can be used to fetch or discard results.</returns>
+    /// <exception cref="InvalidOperationException">Thrown if results are not yet ready.</exception>
+    public QueryResultHandle ResultHandle()
+    {
+        if (!ResultsReady)
+        {
+            throw new InvalidOperationException(
+                $"Results are not ready. Current status: {Status ?? "unknown"}. " +
+                "Poll again with FetchStatusAsync() until ResultsReady is true.");
+        }
+
+        return new QueryResultHandle(_resultHandlePath!, _requestId, _root, _analyticsService);
+    }
+
+    /// <inheritdoc />
+    public override string ToString()
+    {
+        var parts = new List<string>
+        {
+            $"Status={Status ?? "unknown"}",
+            $"ResultsReady={ResultsReady}"
+        };
+
+        if (ResultCount.HasValue)
+        {
+            parts.Add($"ResultCount={ResultCount}");
+        }
+
+        if (ResultSetOrdered.HasValue)
+        {
+            parts.Add($"ResultSetOrdered={ResultSetOrdered}");
+        }
+
+        if (PartitionCount > 0)
+        {
+            parts.Add($"Partitions={PartitionCount}");
+        }
+
+        if (CreatedAt is not null)
+        {
+            parts.Add($"CreatedAt={CreatedAt}");
+        }
+
+        if (Metrics is not null)
+        {
+            var metricParts = new List<string>();
+
+            if (Metrics.ElapsedTime.HasValue)
+                metricParts.Add($"ElapsedTime={Metrics.ElapsedTime.Value.TotalMilliseconds:F1}ms");
+            if (Metrics.ExecutionTime.HasValue)
+                metricParts.Add($"ExecutionTime={Metrics.ExecutionTime.Value.TotalMilliseconds:F1}ms");
+            if (Metrics.CompileTime.HasValue)
+                metricParts.Add($"CompileTime={Metrics.CompileTime.Value.TotalMilliseconds:F1}ms");
+            if (Metrics.QueueWaitTime.HasValue)
+                metricParts.Add($"QueueWaitTime={Metrics.QueueWaitTime.Value.TotalMilliseconds:F1}ms");
+            if (Metrics.ProcessedObjects.HasValue)
+                metricParts.Add($"ProcessedObjects={Metrics.ProcessedObjects}");
+
+            parts.Add(metricParts.Count > 0
+                ? $"Metrics={{{string.Join(", ", metricParts)}}}"
+                : "Metrics={none}");
+        }
+
+        return $"QueryStatus [{string.Join(", ", parts)}]";
+    }
+}