couchbase 3.4.2 → 3.4.4

data/ext/couchbase/couchbase/transactions/transaction_query_options.hxx

@@ -26,6 +26,12 @@ namespace couchbase::transactions
 {
 class transaction_context;
 
+/**
+ * The transaction_query_options are options specific to a query.
+ *
+ * Some of the options will override the corresponding elements in the @ref transactions_query_config section of the
+ * @ref transactions_config.
+ */
 class transaction_query_options
 {
   public:
@@ -34,120 +40,227 @@ class transaction_query_options
         // set defaults specific to query in transactions.
         opts_.metrics(true);
     }
-    /*transaction_query_options(const core::operations::query_request& req)
-      : query_req_(req)
-    {
-    }*/
 
+    /**
+     * Set an option which isn't exposed explicitly in transaction_query_options.
+     *
+     * @see query_options::raw for details.
+     *
+     * @tparam Value type of the value.
+     * @param key The name of the option.
+     * @param value The value of this option.
+     * @return reference to this object, convenient for chaining calls.
+     */
     template<typename Value>
     transaction_query_options& raw(const std::string& key, const Value& value)
     {
         opts_.raw(key, value);
         return *this;
     }
-
+    /**
+     * Set ad_hoc.
+     *
+     * Inform query service that this query is, or is not, a prepared statement query.   @see query_options::adhoc for
+     * detailed discussion.
+     *
+     * @param value if set to false this query will be turned into a prepared statement query.
+     * @return reference to this object, convenient for chaining calls.
+     */
     transaction_query_options& ad_hoc(bool value)
     {
         opts_.adhoc(value);
         return *this;
     }
-
+    /**
+     * Set the query_scan_consistency for this query.
+     *
+     * @see query_options::scan_consistency for details.
+     *
+     * @param scan_consistency Desired scan consistency.
+     * @return reference to this object, convenient for chaining calls.
+     */
     transaction_query_options& scan_consistency(query_scan_consistency scan_consistency)
     {
         opts_.scan_consistency(scan_consistency);
         return *this;
     }
 
+    /**
+     * Set the profile mode for this query.
+     *
+     * @see query_options::profile for details.
+     *
+     * @param mode desired profile mode.
+     * @return reference to this object, convenient for chaining calls.
+     */
     transaction_query_options& profile(query_profile mode)
     {
         opts_.profile(mode);
         return *this;
     }
-
+    /**
+     * Set a client id for this query.
+     *
+     * @see query_options::client_context_id for details.
+     *
+     * @param id Desired id
+     * @return reference to this object, convenient for chaining calls.
+     */
     transaction_query_options& client_context_id(const std::string& id)
     {
         opts_.client_context_id(id);
         return *this;
     }
 
+    /**
+     * Set the scan_wait time
+     *
+     * @see query_options::scan_wait for details.
+     *
+     * @param scan_wait Desired time for scan_wait.
+     * @return reference to this object, convenient for chaining calls.
+     */
     transaction_query_options& scan_wait(std::chrono::milliseconds scan_wait)
     {
         opts_.scan_wait(scan_wait);
         return *this;
     }
 
+    /**
+     * Set the readonly hint for this query.
+     *
+     * @see query_options::readonly
+     *
+     * @param readonly True if query doesn't mutate documents.
+     * @return reference to this object, convenient for chaining calls.
+     */
     transaction_query_options& readonly(bool readonly)
     {
         opts_.readonly(readonly);
         return *this;
     }
-
+    /**
+     * Set the scan cap for this query.
+     *
+     * @see query_options::scan_cap for details.
+     *
+     * @param cap Desired cap.
+     * @return reference to this object, convenient for chaining calls.
+     */
     transaction_query_options& scan_cap(std::uint64_t cap)
     {
         opts_.scan_cap(cap);
         return *this;
     }
-
+    /**
+     * Set pipeline_batch size for this query.
+     *
+     * @see query_options::pipeline_batch for details.
+     *
+     * @param batch desired batch size.
+     * @return reference to this object, convenient for chaining calls.
+     */
     transaction_query_options& pipeline_batch(std::uint64_t batch)
     {
         opts_.pipeline_batch(batch);
         return *this;
     }
 
+    /**
+     * Set pipeline cap for this query.
+     *
+     * @see query_options::pipeline_cap for details.
+     *
+     * @param cap desired cap.
+     * @return reference to this object, convenient for chaining calls.
+     */
     transaction_query_options& pipeline_cap(std::uint64_t cap)
     {
         opts_.pipeline_cap(cap);
         return *this;
     }
 
+    /**
+     * Set positional parameters for this query.
+     *
+     * @see query_options::positional_parameters for details.
+     *
+     * @tparam Parameters Types of the parameters
+     * @param parameters the sequence of positional parameters for this query.
+     * @return reference to this object, convenient for chaining calls.
+     */
     template<typename... Parameters>
     auto positional_parameters(const Parameters&... parameters)
     {
         opts_.positional_parameters(parameters...);
         return *this;
     }
-
+    /**
+     * Set named parameters for this query.
+     *
+     * @see query_options::named_parameters for details.
+     *
+     * @tparam Parameters Types of the parameter pairs.
+     * @param parameters the sequence of name-value pairs. Each value will be encoded into JSON.
+     * @return reference to this object, convenient for chaining calls.
+     */
     template<typename... Parameters>
     transaction_query_options& named_parameters(const Parameters&... parameters)
     {
         opts_.named_parameters(parameters...);
         return *this;
     }
-
+    /**
+     * Set metrics for this query.
+     *
+     * If true, the query results will contain metrics.  This is true by default for transactional queries.
+     * @see query_options::metrics for details.
+     *
+     * @param metrics True if metrics are desired.
+     * @return reference to this object, convenient for chaining calls.
+     */
     transaction_query_options& metrics(bool metrics)
     {
         opts_.metrics(metrics);
         return *this;
     }
 
+    /**
+     * Set max parallelism for this query.
+     *
+     * @see query_options::max_parallelism for details.
+     *
+     * @param max Desired max parallelism
+     * @return reference to this object, convenient for chaining calls.
+     */
     transaction_query_options& max_parallelism(std::uint64_t max)
     {
         opts_.max_parallelism(max);
         return *this;
     }
 
-    /** @internal */
+    /** @private */
     transaction_query_options& encoded_raw_options(std::map<std::string, codec::binary, std::less<>> options)
     {
         opts_.encoded_raw_options(options);
         return *this;
     }
 
-    /** @internal */
+    /** @private */
     transaction_query_options& encoded_positional_parameters(std::vector<codec::binary> parameters)
     {
         opts_.encoded_positional_parameters(parameters);
         return *this;
     }
 
-    /** @internal */
+    /** @private */
     transaction_query_options& encoded_named_parameters(std::map<std::string, codec::binary, std::less<>> parameters)
     {
         opts_.encoded_named_parameters(parameters);
         return *this;
     }
 
-    /** @internal */
+    /** @private */
     const query_options& get_query_options() const
     {
         return opts_;

data/ext/couchbase/couchbase/transactions/transaction_query_result.hxx

@@ -20,6 +20,10 @@
 
 namespace couchbase::transactions
 {
+/**
+ * Transactional queries will return a transaction_query_result.   Note that this is currently identical
+ * to a @ref query_result.   See @ref query_result for details.
+ */
 class transaction_query_result : public query_result
 {
   public:

data/ext/couchbase/couchbase/transactions/transaction_result.hxx

@@ -25,7 +25,7 @@ namespace couchbase::transactions
  * @volatile
  *
  * Contains internal information on a transaction,
- * returned by @ref core::transactions::run()
+ * returned by @ref couchbase::transactions::transactions::run()
  */
 struct transaction_result {
     std::string transaction_id;

data/ext/couchbase/couchbase/transactions/transactions_cleanup_config.hxx

@@ -21,7 +21,9 @@
 #include <couchbase/transactions/transaction_keyspace.hxx>
 namespace couchbase::transactions
 {
-
+/**
+ * Configuration parameters for the background transaction cleanup threads.
+ */
 class transactions_cleanup_config
 {
   public:
@@ -117,7 +119,7 @@ class transactions_cleanup_config
         return *this;
     }
 
-    /** @internal */
+    /** @private */
     struct built {
         bool cleanup_lost_attempts;
         bool cleanup_client_attempts;
@@ -125,7 +127,7 @@ class transactions_cleanup_config
         std::list<couchbase::transactions::transaction_keyspace> collections;
     };
 
-    /** @internal */
+    /** @private */
     [[nodiscard]] auto build() const -> built
     {
         return { cleanup_lost_attempts_, cleanup_client_attempts_, cleanup_window_, collections_ };

data/ext/couchbase/couchbase/transactions/transactions_config.hxx

@@ -53,6 +53,8 @@ class transactions_config
     /**
      * @brief Get the default durability level for all transaction operations
      *
+     * @see couchbase::durability_level for details.
+     *
      * @return The default durability level used for write operations.
      */
     [[nodiscard]] couchbase::durability_level durability_level() const
@@ -63,6 +65,8 @@ class transactions_config
     /**
      * @brief Set the default durability level for all transaction operations
      *
+     * @see couchbase::durability_level for details.
+     *
      * @param level The default durability level desired for write operations.
      * @return reference to this, so calls can be chained.
      */
@@ -115,7 +119,7 @@ class transactions_config
     /**
      * @brief Set the expiration time for transactions.
      *
-     * @param duration desired expiration for transactions. see @ref expiration_time().
+     * @param duration desired expiration for transactions.
      * @return reference to this, so calls can be chained.
      */
     template<typename T>
@@ -206,7 +210,7 @@ class transactions_config
         return *this;
     }
 
-    /** @internal */
+    /** @private */
     transactions_config& test_factories(std::shared_ptr<core::transactions::attempt_context_testing_hooks> hooks,
                                         std::shared_ptr<core::transactions::cleanup_testing_hooks> cleanup_hooks)
     {
@@ -215,19 +219,19 @@ class transactions_config
         return *this;
     }
 
-    /** @internal */
+    /** @private */
     [[nodiscard]] core::transactions::attempt_context_testing_hooks& attempt_context_hooks() const
     {
         return *attempt_context_hooks_;
     }
 
-    /** @internal */
+    /** @private */
     [[nodiscard]] core::transactions::cleanup_testing_hooks& cleanup_hooks() const
     {
         return *cleanup_hooks_;
     }
 
-    /** @internal */
+    /** @private */
     struct built {
         couchbase::durability_level level;
         std::chrono::nanoseconds expiration_time;

data/ext/couchbase/couchbase/transactions/transactions_query_config.hxx

@@ -19,11 +19,14 @@
 
 namespace couchbase::transactions
 {
+/**
+ * The transactions_query_config sets the defaults for all queries in the transactions.
+ */
 class transactions_query_config
 {
   public:
     /**
-     * Set scan consistency for transactions.
+     * Set scan consistency for transactions.  @see query_options::scan_consistency for details.
      *
      * @param consistency the query_scan_consistency to use.
      * @return reference to this, so calls can be chained.
@@ -44,12 +47,12 @@ class transactions_query_config
         return scan_consistency_;
     }
 
-    /** @internal */
+    /** @private */
     struct built {
         query_scan_consistency scan_consistency;
     };
 
-    /** @internal */
+    /** @private */
     [[nodiscard]] auto build() const -> built
     {
         return { scan_consistency_ };

data/ext/couchbase/couchbase/transactions.hxx

@@ -30,14 +30,47 @@ using txn_logic = std::function<void(attempt_context&)>;
 using async_txn_logic = std::function<void(async_attempt_context&)>;
 using async_txn_complete_logic = std::function<void(couchbase::transaction_error_context, transaction_result)>;
 
+/**
+ * The transactions object is used to initiate a transaction.
+ *
+ *
+ */
 class transactions
 {
   public:
     virtual ~transactions() = default;
+
+    /**
+     * Run a blocking transaction.
+     *
+     * You can supply a lambda or function which uses a yielded {@link attempt_context} to perform a transaction, where each transaction
+     * operation is blocking.  A simple usage would be to get a document and replace the contents:
+     *
+     * @snippet{trimleft} test/test_transaction_examples.cxx simple-blocking-txn
+     *
+     * @param logic a lambda or function which uses the yielded {@link attempt_context} to perform the desired transactional operations.
+     * @param cfg if passed in, these options override the defaults, or those set in the {@link cluster_options}.
+     * @return an {@link transaction_error_context}, and a {@link transaction_result} representing the results of the transaction.
+     */
     virtual std::pair<transaction_error_context, transaction_result> run(txn_logic&& logic,
                                                                          const transaction_options& cfg = transaction_options()) = 0;
+    /**
+     * Run an asynchronous transaction.
+     *
+     * You can supply a lambda or function which uses a yielded {@link async_attempt_context} to perform a transaction, where each
+     * transaction operation is asynchronous.  A simple usage would be to get 3 document and replace the contents of each.   In the example
+     * below, we get the 3 documents in parallel, and update each when the get returns the document.   This can be significantly faster than
+     * getting each document in serial, and updating it using the blocking api:
+     *
+     * @snippet{trimleft} test/test_transaction_examples.cxx simple-async-txn
+     *
+     * @param logic a lambda or function which uses the yielded {@link async_attempt_context} to perform the desired transactional
+     * operations.
+     * @param complete_callback a lambda or function to which is yielded a {transaction_error_context} and {transaction_result}.
+     * @param cfg if passed in, these options override the defaults, or those set in the {@link cluster_options}.
+     */
     virtual void run(async_txn_logic&& logic,
                      async_txn_complete_logic&& complete_callback,
                      const transaction_options& cfg = transaction_options()) = 0;
 };
-} // namespace couchbase::transactions
+} // namespace couchbase::transactions

data/ext/couchbase/couchbase/unlock_options.hxx

@@ -89,8 +89,8 @@ initiate_unlock_operation(std::shared_ptr<couchbase::core::cluster> core,
                           std::string collection_name,
                           std::string document_key,
                           couchbase::cas cas,
-                          unlock_options::built options,
-                          unlock_handler&& handler);
+                          couchbase::unlock_options::built options,
+                          couchbase::unlock_handler&& handler);
 #endif
 } // namespace impl
 } // namespace core

data/ext/couchbase/couchbase/update_bucket_options.hxx

@@ -0,0 +1,41 @@
+/* -*- 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 <functional>
+#include <memory>
+#include <optional>
+#include <string>
+
+namespace couchbase
+{
+struct update_bucket_options : public common_options<update_bucket_options> {
+  public:
+    struct built : public common_options<update_bucket_options>::built {
+    };
+
+    [[nodiscard]] auto build() const -> built
+    {
+        return { build_common_options() };
+    }
+
+  private:
+};
+
+using update_bucket_handler = std::function<void(couchbase::manager_error_context)>;
+} // namespace couchbase

data/ext/couchbase/couchbase/upsert_options.hxx

@@ -149,9 +149,9 @@ initiate_upsert_operation(std::shared_ptr<couchbase::core::cluster> core,
                           std::string scope_name,
                           std::string collection_name,
                           std::string document_key,
-                          codec::encoded_value encoded,
-                          upsert_options::built options,
-                          upsert_handler&& handler);
+                          couchbase::codec::encoded_value encoded,
+                          couchbase::upsert_options::built options,
+                          couchbase::upsert_handler&& handler);
 #endif
 } // namespace impl
 } // namespace core

data/ext/couchbase/couchbase/watch_query_indexes_options.hxx

@@ -81,35 +81,4 @@ class watch_query_indexes_options : public common_options<watch_query_indexes_op
  */
 
 using watch_query_indexes_handler = std::function<void(couchbase::manager_error_context)>;
-
-#ifndef COUCHBASE_CXX_CLIENT_DOXYGEN
-namespace core
-{
-class cluster;
-class query_context;
-namespace impl
-{
-
-/**
- * @since 1.0.0
- * @internal
- */
-void
-initiate_watch_query_indexes(std::shared_ptr<couchbase::core::cluster> core,
-                             std::string bucket_name,
-                             std::vector<std::string> index_names,
-                             couchbase::watch_query_indexes_options::built options,
-                             query_context query_ctx,
-                             std::string collection_name,
-                             watch_query_indexes_handler&& handler);
-void
-initiate_watch_query_indexes(std::shared_ptr<couchbase::core::cluster> core,
-                             std::string bucket_name,
-                             std::vector<std::string> index_names,
-                             couchbase::watch_query_indexes_options::built options,
-                             watch_query_indexes_handler&& handler);
-
-#endif
-} // namespace impl
-} // namespace core
 } // namespace couchbase

data/ext/couchbase/couchbase/wildcard_query.hxx

@@ -0,0 +1,83 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2023-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/search_query.hxx>
+
+#include <optional>
+#include <string>
+
+namespace couchbase
+{
+/**
+ * A wildcard query is a query in which term the character `*` will match `0..n` occurrences of any characters and `?` will match `1`
+ * occurrence of any character.
+ *
+ * Match documents where field `reviews.content` contains words starting with `"inter"`:
+ * @snippet test_unit_search.cxx search-wildcard
+ *
+ * @see https://docs.couchbase.com/server/current/fts/fts-supported-queries-wildcard.html server documentation
+ *
+ * @since 1.0.0
+ * @committed
+ */
+class wildcard_query : public search_query
+{
+  public:
+    /**
+     * Create a new wildcard query.
+     *
+     * @param regexp the wildcard-containing term to be analyzed and searched
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    explicit wildcard_query(std::string regexp)
+      : wildcard_{ std::move(regexp) }
+    {
+    }
+
+    /**
+     * If a field is specified, only terms in that field will be matched.
+     *
+     * @param field_name name of the field to be matched
+     *
+     * @return this query for chaining purposes.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    auto field(std::string field_name) -> wildcard_query&
+    {
+        field_ = std::move(field_name);
+        return *this;
+    }
+
+    /**
+     * @return encoded representation of the query.
+     *
+     * @since 1.0.0
+     * @internal
+     */
+    [[nodiscard]] auto encode() const -> encoded_search_query override;
+
+  private:
+    std::string wildcard_;
+    std::optional<std::string> field_{};
+};
+} // namespace couchbase

data/ext/couchbase/test/CMakeLists.txt

@@ -25,18 +25,21 @@ unit_test(json_streaming_lexer)
 unit_test(jsonsl)
 unit_test(config_profiles)
 unit_test(options)
+unit_test(search)
+unit_test(query)
 target_link_libraries(test_unit_jsonsl jsonsl)
 
 integration_benchmark(get)
 
-transaction_test(transaction_context)
-transaction_test(transaction_simple)
-transaction_test(transaction_simple_async)
-transaction_test(transaction_public_blocking_api)
-transaction_test(transaction_public_async_api)
+transaction_test(context)
+transaction_test(simple)
+transaction_test(simple_async)
+transaction_test(public_blocking_api)
+transaction_test(public_async_api)
 
 unit_test(transaction_logging)
 unit_test(transaction_utils)
 unit_test(waitable_op_list)
 
 integration_test(examples)
+transaction_test(examples)

data/ext/couchbase/test/benchmark_helper_integration.hxx

@@ -17,6 +17,6 @@
 
 #pragma once
 
-#define CATCH_CONFIG_ENABLE_BENCHMARKING
-
 #include "test_helper_integration.hxx"
+
+#include <catch2/benchmark/catch_benchmark.hpp>