couchbase 3.8.2 → 3.9.0

data/ext/couchbase/couchbase/query_row.hxx

@@ -0,0 +1,111 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2020-Present 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.
+ */
+
+#pragma once
+
+#include <couchbase/codec/encoded_value.hxx>
+#include <couchbase/codec/serializer_traits.hxx>
+#include <utility>
+
+namespace couchbase
+{
+
+namespace codec
+{
+class tao_json_serializer;
+} // namespace codec
+
+/**
+ * Represents a single row of a streaming query result.
+ *
+ * The raw JSON bytes can be decoded via @ref content_as().
+ *
+ * @since 1.4.0
+ * @volatile
+ */
+class query_row
+{
+public:
+  /**
+   * @since 1.4.0
+   * @volatile
+   */
+  query_row() = default;
+
+  /**
+   * Constructs a row from raw JSON bytes.
+   *
+   * @param content raw JSON bytes for this row
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  explicit query_row(codec::binary content)
+    : content_{ std::move(content) }
+  {
+  }
+
+  /**
+   * Decodes the row content into the requested document type using the given serializer.
+   *
+   * Only call this on a row obtained from a successful @ref query_stream_result#next() (falsy
+   * error, engaged optional). The end-of-stream and error sentinels carry an empty @ref query_row,
+   * and decoding empty/malformed content throws the serializer's parse exception — gate on the
+   * three-state next() contract (check the error, then the optional) before decoding.
+   *
+   * Any type with a serializer-compatible specialization works as the document type:
+   *
+   * @snippet{trimleft} test_integration_examples_streaming.cxx streaming-product
+   *
+   * Usage:
+   *
+   * @snippet{trimleft} test_integration_examples_streaming.cxx example-query-stream
+   *
+   * @tparam Serializer the serializer to use (defaults to @ref codec::tao_json_serializer)
+   * @tparam Document the document type to decode into (defaults to the serializer's document_type)
+   * @return the decoded document
+   * @throws the serializer's deserialization exception if the content is empty or not valid JSON
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  template<typename Serializer = codec::tao_json_serializer,
+           typename Document = typename Serializer::document_type,
+           std::enable_if_t<codec::is_serializer_v<Serializer>, bool> = true>
+  [[nodiscard]] auto content_as() const -> Document
+  {
+    return Serializer::template deserialize<Document>(content_);
+  }
+
+  /**
+   * Returns the raw binary content of this row.
+   *
+   * @return raw JSON bytes
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  [[nodiscard]] auto content_as_binary() const -> const codec::binary&
+  {
+    return content_;
+  }
+
+private:
+  codec::binary content_{};
+};
+
+} // namespace couchbase

data/ext/couchbase/couchbase/query_stream_result.hxx

@@ -0,0 +1,302 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2026. 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.
+ */
+
+#pragma once
+
+#include <couchbase/codec/encoded_value.hxx>
+#include <couchbase/error.hxx>
+#include <couchbase/query_meta_data.hxx>
+#include <couchbase/query_row.hxx>
+
+#include <functional>
+#include <future>
+#include <memory>
+#include <optional>
+#include <utility>
+
+namespace couchbase
+{
+#ifndef COUCHBASE_CXX_CLIENT_DOXYGEN
+class internal_query_stream_result;
+#endif
+
+/**
+ * The signature for the handler of the @ref query_stream_result#next() operation.
+ *
+ * @since 1.4.0
+ * @volatile
+ */
+using query_row_handler = std::function<void(error, std::optional<query_row>)>;
+
+/**
+ * A streaming result handle for N1QL queries.
+ *
+ * Rows are fetched one at a time via @ref next(). The stream must be fully drained
+ * (or @ref cancel() called) before @ref meta_data() resolves. Only a single @ref next()
+ * call may be outstanding at a time.
+ *
+ * @snippet{trimleft} test_integration_examples_streaming.cxx example-query-stream
+ *
+ * @note The future-returning overloads (`next()`, `meta_data()`) and the eager @ref iterator
+ * block the calling thread until the result is ready. They must not be called from within an SDK
+ * completion handler (i.e. the library's I/O thread) — doing so blocks that thread against itself
+ * and the stream can never advance. From a completion handler, use the callback @ref next()
+ * overload instead.
+ *
+ * @note Copies of a result handle share one underlying stream: they alias the same rows, the same
+ * single-outstanding-next() budget, and the same @ref cancel(). Copying does not fork the stream;
+ * a @ref next() on any copy consumes the next row for all of them. Use a single handle per stream.
+ *
+ * @since 1.4.0
+ * @volatile
+ */
+class query_stream_result
+{
+public:
+  /**
+   * Constructs an empty (no-op) result handle.
+   *
+   * @since 1.4.0
+   * @internal
+   */
+  query_stream_result() = default;
+
+  /**
+   * Constructs a query stream result from an internal result.
+   *
+   * @param internal the internal result handle
+   *
+   * @since 1.4.0
+   * @internal
+   */
+  explicit query_stream_result(std::shared_ptr<internal_query_stream_result> internal);
+
+  /**
+   * Fetches the next row asynchronously, invoking the handler when ready.
+   *
+   * The handler receives ({}, row) for a real row, ({}, {}) at clean end-of-stream,
+   * or (error, {}) if the stream ended with an error.
+   *
+   * Only one outstanding call is allowed at a time.
+   *
+   * This is the overload to use from a completion handler: issuing the following pull from inside
+   * the handler drains the stream without ever blocking a thread.
+   *
+   * @snippet{trimleft} test_integration_examples_streaming.cxx example-query-stream-async
+   *
+   * @param handler callable that implements @ref query_row_handler
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  void next(query_row_handler&& handler) const;
+
+  /**
+   * Fetches the next row, returning a future.
+   *
+   * Only one outstanding call is allowed at a time.
+   *
+   * A failure reaches the caller through one of two channels — the error returned by the
+   * originating @ref cluster#query_stream() (the request never started) or the stream's terminal
+   * delivered here. Which one fires is not fixed, so both have to be handled. Once a terminal has
+   * been reached it is re-delivered on every further call rather than blocking on a drained stream:
+   *
+   * @snippet{trimleft} test_integration_examples_streaming.cxx example-query-stream-errors
+   *
+   * @return future object that carries the result of the operation
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  [[nodiscard]] auto next() const -> std::future<std::pair<error, std::optional<query_row>>>;
+
+  /**
+   * Returns the query signature captured from the response metadata, if present.
+   *
+   * The signature is part of the response preamble, so — unlike @ref meta_data() — it is available
+   * as soon as the stream has started, without draining it first:
+   *
+   * @snippet{trimleft} test_integration_examples_streaming.cxx example-query-stream
+   *
+   * @return optional binary JSON signature
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  [[nodiscard]] auto signature() const -> std::optional<codec::binary>;
+
+  /**
+   * Returns the query metadata.
+   *
+   * The returned future resolves only after the stream has been fully drained
+   * (all rows consumed or the stream cancelled). May be called more than once;
+   * each call returns its own future and all of them resolve together once the
+   * metadata becomes available.
+   *
+   * If the stream ended with an error, or was torn down by @ref cancel() before reaching a natural
+   * terminal, the returned future resolves with that error instead of waiting for a trailer that
+   * will never arrive:
+   *
+   * @snippet{trimleft} test_integration_examples_streaming.cxx example-query-stream-errors
+   *
+   * @return future carrying (error, query_meta_data)
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  [[nodiscard]] auto meta_data() const -> std::future<std::pair<error, query_meta_data>>;
+
+  /**
+   * Cancels the stream and closes the underlying HTTP connection.
+   *
+   * Simply dropping the last handle before the stream is fully drained also tears the stream down,
+   * but if a pull is in flight the underlying connection is not released until that pull settles
+   * (up to the inter-read idle timeout). Call cancel() explicitly for prompt, deterministic
+   * teardown of the connection and its timers.
+   *
+   * Part [2] of the example below consumes only a prefix of a large result and then cancels. The
+   * rows that were never pulled are never transferred, so the cost of a prefix read is proportional
+   * to the prefix rather than to the full result:
+   *
+   * @snippet{trimleft} test_integration_examples_streaming.cxx example-query-stream-iterator
+   *
+   * After cancel(), @ref next() reports @ref errc::common::request_canceled — a terminal that has
+   * to be told apart from a genuine failure. Rows consumed before the cancel remain valid:
+   *
+   * @snippet{trimleft} test_integration_examples_streaming.cxx example-query-stream-errors
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  void cancel() const;
+
+  /**
+   * Sentinel returned by @ref end(). An @ref iterator compares equal to it once the stream has been
+   * fully drained (after any terminal error element). Using a distinct end type means iterators are
+   * only ever compared against the end sentinel, never against one another.
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  struct end_sentinel {
+  };
+
+  /**
+   * A single-pass input iterator that synchronously fetches rows one at a time.
+   *
+   * Dereferencing yields `std::pair<error, query_row>`: for a data row the error is falsy; if the
+   * stream ends with an error, the iterator visits exactly one final element whose error is truthy
+   * (and whose row is empty) before comparing equal to @ref end(). A clean end-of-stream yields no
+   * such element. This guarantees a `for (auto [err, row] : result)` loop can observe a terminal
+   * error rather than silently stopping.
+   *
+   * @snippet{trimleft} test_integration_examples_streaming.cxx example-query-stream-iterator
+   *
+   * Part [2] of the error-handling example shows the terminal element being observed rather than
+   * silently truncating the result:
+   *
+   * @snippet{trimleft} test_integration_examples_streaming.cxx example-query-stream-errors
+   *
+   * This is a minimal single-pass iterator intended for range-based for and manual
+   * `while (it != result.end())` loops. It compares only against @ref end() (never against another
+   * iterator), and provides neither `operator->` nor post-increment, so it is deliberately not a
+   * `LegacyInputIterator` and does not work with `<algorithm>` or `std::distance`. @ref begin()
+   * must be called once.
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  class iterator
+  {
+  public:
+    auto operator*() const -> std::pair<error, query_row>;
+    auto operator++() -> iterator&;
+
+    /**
+     * Constructs an iterator over an internal result; prefer @ref begin().
+     *
+     * @since 1.4.0
+     * @internal
+     */
+    explicit iterator(std::shared_ptr<internal_query_stream_result> internal);
+
+    /**
+     * Compares an iterator against the end sentinel. Provided in both argument orders (and as
+     * both @c == and @c !=) so the range-for idiom, `while (it != result.end())` loops, and wrapper
+     * code all work regardless of which operand is written first. Iterators are intentionally never
+     * comparable to one another: a single-pass stream has one position, so iterator-to-iterator
+     * equality would be meaningless — the type only ever compares against @ref end().
+     */
+    friend auto operator==(const iterator& it, end_sentinel /* end */) -> bool
+    {
+      return it.terminal_;
+    }
+    friend auto operator==(end_sentinel end, const iterator& it) -> bool
+    {
+      return it == end;
+    }
+    friend auto operator!=(const iterator& it, end_sentinel end) -> bool
+    {
+      return !(it == end);
+    }
+    friend auto operator!=(end_sentinel end, const iterator& it) -> bool
+    {
+      return !(it == end);
+    }
+
+    // Intentionally no std::iterator_traits typedefs (notably no iterator_category). This is a
+    // deliberately minimal single-pass iterator for range-based for and `while (it !=
+    // result.end())` loops only (see the class doc); it omits post-increment and operator->.
+    // Declaring an input_iterator_tag while omitting those would falsely advertise
+    // LegacyInputIterator / std::input_iterator conformance and could break generic code that
+    // trusts iterator_traits. Range-based for needs none of these typedefs.
+
+  private:
+    void fetch_item();
+
+    std::shared_ptr<internal_query_stream_result> internal_{};
+    std::pair<error, query_row> item_{};
+    bool terminal_{ false };
+    // Set when fetch_item() lands on a terminal error: the error element is delivered once (the
+    // iterator is not yet equal to end()), and the next increment advances to true end.
+    bool error_pending_{ false };
+  };
+
+  /**
+   * Returns an iterator to the beginning.
+   *
+   * @return iterator to the first row
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  [[nodiscard]] auto begin() const -> iterator;
+
+  /**
+   * Returns the end sentinel.
+   *
+   * @return sentinel that an @ref iterator compares equal to once the stream is drained
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  [[nodiscard]] auto end() const -> end_sentinel;
+
+private:
+  std::shared_ptr<internal_query_stream_result> internal_{};
+};
+} // namespace couchbase

data/ext/couchbase/couchbase/query_string_query.hxx

@@ -31,15 +31,15 @@ namespace couchbase
  * parameter with the number to boost the search. For example perform
  * @ref match_query for pool in both the name and description fields, but documents having the term
  * in the name field score higher.
- * @snippet{trimleft} test_unit_search.cxx search-query-string-boosting
+ * @snippet{trimleft} unit/management/search.cxx search-query-string-boosting
  *
  * 2. You can perform date or numeric range searches by using the `>`, `>=`, `<`, and `<=`
  * operators, followed by a date value in quotes. For example, perform a @ref date_range_query on
  * the created field for values after September 21, 2016.
- * @snippet{trimleft} test_unit_search.cxx search-query-string-date-range
+ * @snippet{trimleft} unit/management/search.cxx search-query-string-date-range
  * Or, perform a @ref numeric_range_query  on the `reviews.ratings.Cleanliness` field, for values
  * greater than 4.
- * @snippet{trimleft} test_unit_search.cxx search-query-string-numeric-range
+ * @snippet{trimleft} unit/management/search.cxx search-query-string-numeric-range
  *
  * @see https://docs.couchbase.com/server/current/fts/fts-query-string-syntax.html definition of
  * query syntax

data/ext/couchbase/couchbase/regexp_query.hxx

@@ -28,7 +28,7 @@ namespace couchbase
  * Finds documents containing terms that match the specified regular expression.
  *
  * Match documents where field `reviews.content` contains words starting with `"inter"`:
- * @snippet{trimleft} test_unit_search.cxx search-regexp
+ * @snippet{trimleft} unit/management/search.cxx search-regexp
  *
  * @see https://docs.couchbase.com/server/current/fts/fts-supported-queries-regexp.html server
  * documentation

data/ext/couchbase/couchbase/replace_options.hxx

@@ -73,8 +73,8 @@ struct replace_options : public common_durability_options<replace_options> {
    *
    * If true, and the document exists, its expiry will not be modified. Otherwise the document's
    * expiry is determined by
-   * {@link #expiry(std::chrono::seconds)} or {@link
-   * #expiry(std::chrono::system_clock::time_point)}.
+   * {@link #expiry expiry(std::chrono::seconds)} or {@link #expiry
+   * expiry(std::chrono::system_clock::time_point)}.
    *
    * Requires Couchbase Server 7.0 or later.
    *
@@ -94,7 +94,7 @@ struct replace_options : public common_durability_options<replace_options> {
    * Sets the expiry for the document. By default the document will never expire.
    *
    * The duration must be less than 50 years. For expiry further in the future, use
-   * {@link #expiry(std::chrono::system_clock::time_point)}.
+   * {@link #expiry expiry(std::chrono::system_clock::time_point)}.
    *
    * @param duration the duration after which the document will expire (zero duration means never
    * expire).

data/ext/couchbase/couchbase/result.hxx

@@ -56,7 +56,7 @@ public:
    * @param node_id identity of the node that served the request
    *
    * @since 1.3.2
-   * @uncommitted
+   * @internal
    */
   result(couchbase::cas cas, couchbase::node_id node_id)
     : cas_(cas)
@@ -65,7 +65,7 @@ public:
   }
 
   /**
-   * @return
+   * @return CAS value associated with the operation result.
    *
    * @since 1.0.0
    * @committed
@@ -92,10 +92,21 @@ public:
   }
 
   /**
+   * Implementation-only setter used by @c core::impl::invoke_with_node_id to
+   * propagate the node identity from a KV error context onto the result.
+   *
+   * Despite living in the public header (it is needed to set the field on
+   * the public-facing result-derived types from a template instantiation in
+   * the impl layer), this is **not** part of the user-facing API. The name
+   * is deliberately noisy — @c @internal alone is documentation-only and
+   * does not stop a user discovering @c result.node_id(...) via
+   * autocomplete; @c set_node_id_internal is harder to mistake for a
+   * documented mutator.
+   *
    * @since 1.3.2
    * @internal
    */
-  void node_id(couchbase::node_id id)
+  void set_node_id_internal(couchbase::node_id id)
   {
     node_id_ = std::move(id);
   }

data/ext/couchbase/couchbase/scan_result_item.hxx

@@ -62,6 +62,7 @@ public:
    * @param cas
    * @param value raw document contents along with flags describing its structure
    * @param expiry_time optional point in time when the document will expire
+   * @param crypto_manager manager handed to the transcoder to decrypt encrypted fields
    *
    * @since 1.0.0
    * @internal

data/ext/couchbase/couchbase/scope.hxx

@@ -113,6 +113,52 @@ public:
   [[nodiscard]] auto query(std::string statement, const query_options& options = {}) const
     -> std::future<std::pair<error, query_result>>;
 
+  /**
+   * Performs a streaming query against the query (N1QL) services.
+   *
+   * The handler resolves as soon as the response preamble has been parsed; rows are then pulled
+   * lazily from the @ref query_stream_result, so the full result is never buffered in memory.
+   *
+   * @note Prepared statements (@ref query_options#adhoc set to false) are not streamed: such a
+   * request falls back to the buffered @ref query() path and its rows are replayed through the
+   * returned handle.
+   *
+   * The handler runs on the library's I/O thread, so the stream must be drained with the callback
+   * @ref query_stream_result#next() overload rather than the blocking ones. The example is written
+   * against @ref cluster#query_stream(), but the scope-level overload behaves identically:
+   *
+   * @snippet{trimleft} test_integration_examples_streaming.cxx example-query-stream-async
+   *
+   * @param statement the N1QL query statement.
+   * @param options options to customize the query request.
+   * @param handler the handler that implements @ref query_stream_handler
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  void query_stream(std::string statement,
+                    const query_options& options,
+                    query_stream_handler&& handler) const;
+
+  /**
+   * Performs a streaming query against the query (N1QL) services.
+   *
+   * Unqualified keyspaces in the statement resolve against this scope, so it names the collection
+   * rather than the bucket. The result can be consumed with a range-based for loop, and abandoned
+   * early without transferring the rows that were never read:
+   *
+   * @snippet{trimleft} test_integration_examples_streaming.cxx example-query-stream-iterator
+   *
+   * @param statement the N1QL query statement.
+   * @param options options to customize the query request.
+   * @return future object that carries the streaming result handle
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  [[nodiscard]] auto query_stream(std::string statement, const query_options& options = {}) const
+    -> std::future<std::pair<error, query_stream_result>>;
+
   /**
    * Performs a request against the full text search services.
    *
@@ -190,8 +236,45 @@ public:
    * @since 1.0.0
    * @committed
    */
-  [[nodiscard]] auto analytics_query(std::string statement, const analytics_options& options = {})
-    const -> std::future<std::pair<error, analytics_result>>;
+  [[nodiscard]] auto analytics_query(std::string statement,
+                                     const analytics_options& options = {}) const
+    -> std::future<std::pair<error, analytics_result>>;
+
+  /**
+   * Performs a streaming query against the analytics services.
+   *
+   * The handler resolves as soon as the response preamble has been parsed; rows are then pulled
+   * lazily from the @ref analytics_stream_result, so the full result is never buffered in memory.
+   *
+   * @param statement the analytics query statement.
+   * @param options options to customize the query request.
+   * @param handler the handler that implements @ref analytics_stream_handler
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  void analytics_query_stream(std::string statement,
+                              const analytics_options& options,
+                              analytics_stream_handler&& handler) const;
+
+  /**
+   * Performs a streaming query against the analytics services.
+   *
+   * The example is written against @ref cluster#analytics_query_stream(), but the scope-level
+   * overload behaves identically apart from resolving the statement against this scope:
+   *
+   * @snippet{trimleft} test_integration_examples_streaming.cxx example-analytics-stream
+   *
+   * @param statement the analytics query statement.
+   * @param options options to customize the query request.
+   * @return future object that carries the streaming result handle
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  [[nodiscard]] auto analytics_query_stream(std::string statement,
+                                            const analytics_options& options = {}) const
+    -> std::future<std::pair<error, analytics_stream_result>>;
 
   /**
    * Provides access to search index management services at the scope level