collection.hpp

// Copyright 2014-present MongoDB 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 <algorithm>
#include <bsoncxx/builder/basic/array.hpp>
#include <bsoncxx/builder/basic/document.hpp>
#include <bsoncxx/builder/basic/kvp.hpp>
#include <bsoncxx/builder/concatenate.hpp>
#include <bsoncxx/document/view_or_value.hpp>
#include <bsoncxx/oid.hpp>
#include <bsoncxx/stdx/optional.hpp>
#include <bsoncxx/string/view_or_value.hpp>
#include <mongocxx/bulk_write.hpp>
#include <mongocxx/change_stream.hpp>
#include <mongocxx/client_session.hpp>
#include <mongocxx/config/prelude.hpp>
#include <mongocxx/cursor.hpp>
#include <mongocxx/index_view.hpp>
#include <mongocxx/model/insert_one.hpp>
#include <mongocxx/options/aggregate.hpp>
#include <mongocxx/options/bulk_write.hpp>
#include <mongocxx/options/change_stream.hpp>
#include <mongocxx/options/count.hpp>
#include <mongocxx/options/delete.hpp>
#include <mongocxx/options/distinct.hpp>
#include <mongocxx/options/estimated_document_count.hpp>
#include <mongocxx/options/find.hpp>
#include <mongocxx/options/find_one_and_delete.hpp>
#include <mongocxx/options/find_one_and_replace.hpp>
#include <mongocxx/options/find_one_and_update.hpp>
#include <mongocxx/options/index.hpp>
#include <mongocxx/options/index_view.hpp>
#include <mongocxx/options/insert.hpp>
#include <mongocxx/options/replace.hpp>
#include <mongocxx/options/update.hpp>
#include <mongocxx/pipeline.hpp>
#include <mongocxx/read_concern.hpp>
#include <mongocxx/read_preference.hpp>
#include <mongocxx/result/bulk_write.hpp>
#include <mongocxx/result/delete.hpp>
#include <mongocxx/result/insert_many.hpp>
#include <mongocxx/result/insert_one.hpp>
#include <mongocxx/result/replace_one.hpp>
#include <mongocxx/result/update.hpp>
#include <mongocxx/write_concern.hpp>
#include <string>
 
namespace mongocxx {
MONGOCXX_INLINE_NAMESPACE_BEGIN
 
class client;
class database;
 
class MONGOCXX_API collection {
    //
    // Utility class supporting the convenience of {} meaning an empty bsoncxx::document.
    //
    // Users may not use this class directly.
    //
    // In places where driver methods take this class as a parameter, passing {} will
    // translate to a default-constructed bsoncxx::document::view_or_value,
    // regardless of other overloads taking other default-constructible types
    // for that parameter. This class avoids compiler ambiguity with such overloads.
    //
    // See collection::update_one for an example of such overloads.
    //
    class _empty_doc_tag {
        _empty_doc_tag() = default;
    };
 
   public:
    collection() noexcept;
 
    collection(collection&&) noexcept;
 
    collection& operator=(collection&&) noexcept;
 
    collection(const collection&);
 
    collection& operator=(const collection&);
 
    ~collection();
 
    explicit operator bool() const noexcept;
 
    cursor aggregate(const pipeline& pipeline,
                     const options::aggregate& options = options::aggregate());
 
    cursor aggregate(const client_session& session,
                     const pipeline& pipeline,
                     const options::aggregate& options = options::aggregate());
 
    class bulk_write create_bulk_write(const options::bulk_write& options = {});
 
    class bulk_write create_bulk_write(const client_session& session,
                                       const options::bulk_write& options = {});
 
    MONGOCXX_INLINE stdx::optional<result::bulk_write> write(
        const model::write& write, const options::bulk_write& options = options::bulk_write());
 
    MONGOCXX_INLINE stdx::optional<result::bulk_write> write(
        const client_session& session,
        const model::write& write,
        const options::bulk_write& options = options::bulk_write());
 
    template <typename container_type>
    MONGOCXX_INLINE stdx::optional<result::bulk_write> bulk_write(
        const container_type& writes, const options::bulk_write& options = options::bulk_write());
 
    template <typename container_type>
    MONGOCXX_INLINE stdx::optional<result::bulk_write> bulk_write(
        const client_session& session,
        const container_type& writes,
        const options::bulk_write& options = options::bulk_write());
 
    template <typename write_model_iterator_type>
    MONGOCXX_INLINE stdx::optional<result::bulk_write> bulk_write(
        write_model_iterator_type begin,
        write_model_iterator_type end,
        const options::bulk_write& options = options::bulk_write());
 
    template <typename write_model_iterator_type>
    MONGOCXX_INLINE stdx::optional<result::bulk_write> bulk_write(
        const client_session& session,
        write_model_iterator_type begin,
        write_model_iterator_type end,
        const options::bulk_write& options = options::bulk_write());
 
    std::int64_t count_documents(bsoncxx::document::view_or_value filter,
                                 const options::count& options = options::count());
 
    std::int64_t count_documents(const client_session& session,
                                 bsoncxx::document::view_or_value filter,
                                 const options::count& options = options::count());
 
    std::int64_t estimated_document_count(
        const options::estimated_document_count& options = options::estimated_document_count());
 
    bsoncxx::document::value create_index(
        bsoncxx::document::view_or_value keys,
        bsoncxx::document::view_or_value index_options = {},
        options::index_view operation_options = options::index_view{});
 
    bsoncxx::document::value create_index(
        const client_session& session,
        bsoncxx::document::view_or_value keys,
        bsoncxx::document::view_or_value index_options = {},
        options::index_view operation_options = options::index_view{});
 
 
    stdx::optional<result::delete_result> delete_many(
        bsoncxx::document::view_or_value filter,
        const options::delete_options& options = options::delete_options());
 
    stdx::optional<result::delete_result> delete_many(
        const client_session& session,
        bsoncxx::document::view_or_value filter,
        const options::delete_options& options = options::delete_options());
 
 
    stdx::optional<result::delete_result> delete_one(
        bsoncxx::document::view_or_value filter,
        const options::delete_options& options = options::delete_options());
 
    stdx::optional<result::delete_result> delete_one(
        const client_session& session,
        bsoncxx::document::view_or_value filter,
        const options::delete_options& options = options::delete_options());
 
 
 
 
    cursor distinct(bsoncxx::string::view_or_value name,
                    bsoncxx::document::view_or_value filter,
                    const options::distinct& options = options::distinct());
 
 
 
    cursor distinct(const client_session& session,
                    bsoncxx::string::view_or_value name,
                    bsoncxx::document::view_or_value filter,
                    const options::distinct& options = options::distinct());
 
 
    void drop(const bsoncxx::stdx::optional<mongocxx::write_concern>& write_concern = {});
 
    void drop(const client_session& session,
              const bsoncxx::stdx::optional<mongocxx::write_concern>& write_concern = {});
 
 
    cursor find(bsoncxx::document::view_or_value filter,
                const options::find& options = options::find());
 
    cursor find(const client_session& session,
                bsoncxx::document::view_or_value filter,
                const options::find& options = options::find());
 
    stdx::optional<bsoncxx::document::value> find_one(
        bsoncxx::document::view_or_value filter, const options::find& options = options::find());
 
    stdx::optional<bsoncxx::document::value> find_one(
        const client_session& session,
        bsoncxx::document::view_or_value filter,
        const options::find& options = options::find());
 
 
    stdx::optional<bsoncxx::document::value> find_one_and_delete(
        bsoncxx::document::view_or_value filter,
        const options::find_one_and_delete& options = options::find_one_and_delete());
 
    stdx::optional<bsoncxx::document::value> find_one_and_delete(
        const client_session& session,
        bsoncxx::document::view_or_value filter,
        const options::find_one_and_delete& options = options::find_one_and_delete());
 
 
    stdx::optional<bsoncxx::document::value> find_one_and_replace(
        bsoncxx::document::view_or_value filter,
        bsoncxx::document::view_or_value replacement,
        const options::find_one_and_replace& options = options::find_one_and_replace());
 
    stdx::optional<bsoncxx::document::value> find_one_and_replace(
        const client_session& session,
        bsoncxx::document::view_or_value filter,
        bsoncxx::document::view_or_value replacement,
        const options::find_one_and_replace& options = options::find_one_and_replace());
 
 
    stdx::optional<bsoncxx::document::value> find_one_and_update(
        bsoncxx::document::view_or_value filter,
        bsoncxx::document::view_or_value update,
        const options::find_one_and_update& options = options::find_one_and_update());
 
    stdx::optional<bsoncxx::document::value> find_one_and_update(
        bsoncxx::document::view_or_value filter,
        const pipeline& update,
        const options::find_one_and_update& options = options::find_one_and_update());
 
    stdx::optional<bsoncxx::document::value> find_one_and_update(
        bsoncxx::document::view_or_value filter,
        std::initializer_list<_empty_doc_tag> update,
        const options::find_one_and_update& options = options::find_one_and_update());
 
    stdx::optional<bsoncxx::document::value> find_one_and_update(
        const client_session& session,
        bsoncxx::document::view_or_value filter,
        bsoncxx::document::view_or_value update,
        const options::find_one_and_update& options = options::find_one_and_update());
 
    stdx::optional<bsoncxx::document::value> find_one_and_update(
        const client_session& session,
        bsoncxx::document::view_or_value filter,
        const pipeline& update,
        const options::find_one_and_update& options = options::find_one_and_update());
 
    stdx::optional<bsoncxx::document::value> find_one_and_update(
        const client_session& session,
        bsoncxx::document::view_or_value filter,
        std::initializer_list<_empty_doc_tag> update,
        const options::find_one_and_update& options = options::find_one_and_update());
 
 
    stdx::optional<result::insert_one> insert_one(bsoncxx::document::view_or_value document,
                                                  const options::insert& options = {});
    stdx::optional<result::insert_one> insert_one(const client_session& session,
                                                  bsoncxx::document::view_or_value document,
                                                  const options::insert& options = {});
 
    template <typename container_type>
    MONGOCXX_INLINE stdx::optional<result::insert_many> insert_many(
        const container_type& container, const options::insert& options = options::insert());
 
    template <typename container_type>
    MONGOCXX_INLINE stdx::optional<result::insert_many> insert_many(
        const client_session& session,
        const container_type& container,
        const options::insert& options = options::insert());
 
    template <typename document_view_iterator_type>
    MONGOCXX_INLINE stdx::optional<result::insert_many> insert_many(
        document_view_iterator_type begin,
        document_view_iterator_type end,
        const options::insert& options = options::insert());
 
    template <typename document_view_iterator_type>
    MONGOCXX_INLINE stdx::optional<result::insert_many> insert_many(
        const client_session& session,
        document_view_iterator_type begin,
        document_view_iterator_type end,
        const options::insert& options = options::insert());
 
    cursor list_indexes() const;
 
    cursor list_indexes(const client_session& session) const;
 
 
    stdx::string_view name() const;
 
    void rename(bsoncxx::string::view_or_value new_name,
                bool drop_target_before_rename = false,
                const bsoncxx::stdx::optional<write_concern>& write_concern = {});
 
    void rename(const client_session& session,
                bsoncxx::string::view_or_value new_name,
                bool drop_target_before_rename = false,
                const bsoncxx::stdx::optional<write_concern>& write_concern = {});
 
 
    void read_concern(class read_concern rc);
 
    class read_concern read_concern() const;
 
    void read_preference(class read_preference rp);
 
    class read_preference read_preference() const;
 
    stdx::optional<result::replace_one> replace_one(
        bsoncxx::document::view_or_value filter,
        bsoncxx::document::view_or_value replacement,
        const options::replace& options = options::replace{});
 
    stdx::optional<result::replace_one> replace_one(
        const client_session& session,
        bsoncxx::document::view_or_value filter,
        bsoncxx::document::view_or_value replacement,
        const options::replace& options = options::replace{});
 
    stdx::optional<result::update> update_many(bsoncxx::document::view_or_value filter,
                                               bsoncxx::document::view_or_value update,
                                               const options::update& options = options::update());
 
    stdx::optional<result::update> update_many(bsoncxx::document::view_or_value filter,
                                               const pipeline& update,
                                               const options::update& options = options::update());
 
    stdx::optional<result::update> update_many(bsoncxx::document::view_or_value filter,
                                               std::initializer_list<_empty_doc_tag> update,
                                               const options::update& options = options::update());
 
    stdx::optional<result::update> update_many(const client_session& session,
                                               bsoncxx::document::view_or_value filter,
                                               bsoncxx::document::view_or_value update,
                                               const options::update& options = options::update());
 
    stdx::optional<result::update> update_many(const client_session& session,
                                               bsoncxx::document::view_or_value filter,
                                               const pipeline& update,
                                               const options::update& options = options::update());
 
    stdx::optional<result::update> update_many(const client_session& session,
                                               bsoncxx::document::view_or_value filter,
                                               std::initializer_list<_empty_doc_tag> update,
                                               const options::update& options = options::update());
 
 
    stdx::optional<result::update> update_one(bsoncxx::document::view_or_value filter,
                                              bsoncxx::document::view_or_value update,
                                              const options::update& options = options::update());
 
    stdx::optional<result::update> update_one(bsoncxx::document::view_or_value filter,
                                              const pipeline& update,
                                              const options::update& options = options::update());
 
    stdx::optional<result::update> update_one(bsoncxx::document::view_or_value filter,
                                              std::initializer_list<_empty_doc_tag> update,
                                              const options::update& options = options::update());
 
    stdx::optional<result::update> update_one(const client_session& session,
                                              bsoncxx::document::view_or_value filter,
                                              bsoncxx::document::view_or_value update,
                                              const options::update& options = options::update());
 
    stdx::optional<result::update> update_one(const client_session& session,
                                              bsoncxx::document::view_or_value filter,
                                              const pipeline& update,
                                              const options::update& options = options::update());
 
    stdx::optional<result::update> update_one(const client_session& session,
                                              bsoncxx::document::view_or_value filter,
                                              std::initializer_list<_empty_doc_tag> update,
                                              const options::update& options = options::update());
 
 
    void write_concern(class write_concern wc);
 
    class write_concern write_concern() const;
 
    index_view indexes();
 
    change_stream watch(const options::change_stream& options = {});
 
    change_stream watch(const client_session& session, const options::change_stream& options = {});
 
    change_stream watch(const pipeline& pipe, const options::change_stream& options = {});
 
    change_stream watch(const client_session& session,
                        const pipeline& pipe,
                        const options::change_stream& options = {});
 
 
   private:
    friend class bulk_write;
    friend class database;
 
    MONGOCXX_PRIVATE collection(const database& database,
                                bsoncxx::string::view_or_value collection_name);
 
    MONGOCXX_PRIVATE collection(const database& database, void* collection);
 
    MONGOCXX_PRIVATE cursor _aggregate(const client_session* session,
                                       const pipeline& pipeline,
                                       const options::aggregate& options);
 
    MONGOCXX_PRIVATE std::int64_t _count(const client_session* session,
                                         bsoncxx::document::view_or_value filter,
                                         const options::count& options);
 
    MONGOCXX_PRIVATE std::int64_t _count_documents(const client_session* session,
                                                   bsoncxx::document::view_or_value filter,
                                                   const options::count& options);
 
    MONGOCXX_PRIVATE bsoncxx::document::value _create_index(
        const client_session* session,
        bsoncxx::document::view_or_value keys,
        bsoncxx::document::view_or_value index_options,
        options::index_view operation_options);
 
    MONGOCXX_PRIVATE stdx::optional<result::delete_result> _delete_many(
        const client_session* session,
        bsoncxx::document::view_or_value filter,
        const options::delete_options& options);
 
    MONGOCXX_PRIVATE stdx::optional<result::delete_result> _delete_one(
        const client_session* session,
        bsoncxx::document::view_or_value filter,
        const options::delete_options& options);
 
    MONGOCXX_PRIVATE cursor _distinct(const client_session* session,
                                      bsoncxx::string::view_or_value name,
                                      bsoncxx::document::view_or_value filter,
                                      const options::distinct& options);
 
    MONGOCXX_PRIVATE void _drop(
        const client_session* session,
        const bsoncxx::stdx::optional<mongocxx::write_concern>& write_concern);
 
    MONGOCXX_PRIVATE cursor _find(const client_session* session,
                                  bsoncxx::document::view_or_value filter,
                                  const options::find& options);
 
    MONGOCXX_PRIVATE stdx::optional<bsoncxx::document::value> _find_one(
        const client_session* session,
        bsoncxx::document::view_or_value filter,
        const options::find& options);
 
    MONGOCXX_PRIVATE stdx::optional<bsoncxx::document::value> _find_one_and_delete(
        const client_session* session,
        bsoncxx::document::view_or_value filter,
        const options::find_one_and_delete& options);
 
    MONGOCXX_PRIVATE stdx::optional<bsoncxx::document::value> _find_one_and_replace(
        const client_session* session,
        bsoncxx::document::view_or_value filter,
        bsoncxx::document::view_or_value replacement,
        const options::find_one_and_replace& options);
 
    MONGOCXX_PRIVATE stdx::optional<bsoncxx::document::value> _find_one_and_update(
        const client_session* session,
        bsoncxx::document::view_or_value filter,
        bsoncxx::document::view_or_value update,
        const options::find_one_and_update& options);
 
    MONGOCXX_PRIVATE stdx::optional<result::insert_one> _insert_one(
        const client_session* session,
        bsoncxx::document::view_or_value document,
        const options::insert& options);
 
    MONGOCXX_PRIVATE void _rename(
        const client_session* session,
        bsoncxx::string::view_or_value new_name,
        bool drop_target_before_rename,
        const bsoncxx::stdx::optional<class write_concern>& write_concern);
 
    MONGOCXX_PRIVATE stdx::optional<result::replace_one> _replace_one(
        const client_session* session,
        const options::bulk_write& bulk_opts,
        const model::replace_one& replace_op);
 
    MONGOCXX_PRIVATE stdx::optional<result::replace_one> _replace_one(
        const client_session* session,
        bsoncxx::document::view_or_value filter,
        bsoncxx::document::view_or_value replacement,
        const options::replace& options);
 
    MONGOCXX_PRIVATE stdx::optional<result::update> _update_one(
        const client_session* session,
        bsoncxx::document::view_or_value filter,
        bsoncxx::document::view_or_value update,
        const options::update& options);
 
    MONGOCXX_PRIVATE stdx::optional<result::update> _update_many(
        const client_session* session,
        bsoncxx::document::view_or_value filter,
        bsoncxx::document::view_or_value update,
        const options::update& options);
 
    MONGOCXX_PRIVATE change_stream _watch(const client_session* session,
                                          const pipeline& pipe,
                                          const options::change_stream& options);
 
    // Helpers for the insert_many method templates.
    class bulk_write _init_insert_many(const options::insert& options,
                                       const client_session* session);
 
    void _insert_many_doc_handler(class bulk_write& writes,
                                  bsoncxx::builder::basic::array& inserted_ids,
                                  bsoncxx::document::view doc) const;
 
    stdx::optional<result::insert_many> _exec_insert_many(
        class bulk_write& writes, bsoncxx::builder::basic::array& inserted_ids);
 
    template <typename document_view_iterator_type>
    MONGOCXX_PRIVATE stdx::optional<result::insert_many> _insert_many(
        const client_session* session,
        document_view_iterator_type begin,
        document_view_iterator_type end,
        const options::insert& options);
 
    class MONGOCXX_PRIVATE impl;
 
    MONGOCXX_PRIVATE impl& _get_impl();
    MONGOCXX_PRIVATE const impl& _get_impl() const;
 
    std::unique_ptr<impl> _impl;
};
 
MONGOCXX_INLINE stdx::optional<result::bulk_write> collection::write(
    const model::write& write, const options::bulk_write& options) {
    return create_bulk_write(options).append(write).execute();
}
 
MONGOCXX_INLINE stdx::optional<result::bulk_write> collection::write(
    const client_session& session, const model::write& write, const options::bulk_write& options) {
    return create_bulk_write(session, options).append(write).execute();
}
 
template <typename container_type>
MONGOCXX_INLINE stdx::optional<result::bulk_write> collection::bulk_write(
    const container_type& requests, const options::bulk_write& options) {
    return bulk_write(requests.begin(), requests.end(), options);
}
 
template <typename container_type>
MONGOCXX_INLINE stdx::optional<result::bulk_write> collection::bulk_write(
    const client_session& session,
    const container_type& requests,
    const options::bulk_write& options) {
    return bulk_write(session, requests.begin(), requests.end(), options);
}
 
template <typename write_model_iterator_type>
MONGOCXX_INLINE stdx::optional<result::bulk_write> collection::bulk_write(
    write_model_iterator_type begin,
    write_model_iterator_type end,
    const options::bulk_write& options) {
    auto writes = create_bulk_write(options);
    std::for_each(begin, end, [&](const model::write& current) { writes.append(current); });
    return writes.execute();
}
 
template <typename write_model_iterator_type>
MONGOCXX_INLINE stdx::optional<result::bulk_write> collection::bulk_write(
    const client_session& session,
    write_model_iterator_type begin,
    write_model_iterator_type end,
    const options::bulk_write& options) {
    auto writes = create_bulk_write(session, options);
    std::for_each(begin, end, [&](const model::write& current) { writes.append(current); });
    return writes.execute();
}
 
template <typename container_type>
MONGOCXX_INLINE stdx::optional<result::insert_many> collection::insert_many(
    const container_type& container, const options::insert& options) {
    return insert_many(container.begin(), container.end(), options);
}
 
template <typename container_type>
MONGOCXX_INLINE stdx::optional<result::insert_many> collection::insert_many(
    const client_session& session,
    const container_type& container,
    const options::insert& options) {
    return insert_many(session, container.begin(), container.end(), options);
}
 
template <typename document_view_iterator_type>
MONGOCXX_INLINE stdx::optional<result::insert_many> collection::_insert_many(
 
    const client_session* session,
    document_view_iterator_type begin,
    document_view_iterator_type end,
    const options::insert& options) {
    bsoncxx::builder::basic::array inserted_ids;
    auto writes = _init_insert_many(options, session);
    std::for_each(begin, end, [&inserted_ids, &writes, this](bsoncxx::document::view doc) {
        _insert_many_doc_handler(writes, inserted_ids, doc);
    });
    return _exec_insert_many(writes, inserted_ids);
}
 
template <typename document_view_iterator_type>
MONGOCXX_INLINE stdx::optional<result::insert_many> collection::insert_many(
    document_view_iterator_type begin,
    document_view_iterator_type end,
    const options::insert& options) {
    return _insert_many(nullptr, begin, end, options);
}
 
template <typename document_view_iterator_type>
MONGOCXX_INLINE stdx::optional<result::insert_many> collection::insert_many(
    const client_session& session,
    document_view_iterator_type begin,
    document_view_iterator_type end,
    const options::insert& options) {
    return _insert_many(&session, begin, end, options);
}
 
MONGOCXX_INLINE_NAMESPACE_END
}  // namespace mongocxx
 
#include <mongocxx/config/postlude.hpp>