1MongoDB::BulkWrite(3) User Contributed Perl DocumentationMongoDB::BulkWrite(3)
2
3
4

NAME

6       MongoDB::BulkWrite - MongoDB bulk write interface
7

VERSION

9       version v2.2.2
10

SYNOPSIS

12           use Safe::Isa;
13           use Try::Tiny;
14
15           my $bulk = $collection->initialize_ordered_bulk_op;
16
17           $bulk->insert_one( $doc );
18           $bulk->find( $query )->upsert->replace_one( $doc )
19           $bulk->find( $query )->update( $modification )
20
21           my $result = try {
22               $bulk->execute;
23           }
24           catch {
25               if ( $_->$isa("MongoDB::WriteConcernError") ) {
26                   warn "Write concern failed";
27               }
28               else {
29                   die $_;
30               }
31           };
32

DESCRIPTION

34       This class constructs a list of write operations to perform in bulk for
35       a single collection.  On a MongoDB 2.6 or later server with write
36       command support this allow grouping similar operations together for
37       transit to the database, minimizing network round-trips.
38
39       To begin a bulk operation, use one these methods from
40       MongoDB::Collection:
41
42       •   initialize_ordered_bulk_op
43
44       •   initialize_unordered_bulk_op
45
46   Ordered Operations
47       With an ordered operations list, MongoDB executes the write operations
48       in the list serially. If an error occurs during the processing of one
49       of the write operations, MongoDB will return without processing any
50       remaining write operations in the list.
51
52   Unordered Operations
53       With an unordered operations list, MongoDB can execute in parallel, as
54       well as in a nondeterministic order, the write operations in the list.
55       If an error occurs during the processing of one of the write
56       operations, MongoDB will continue to process remaining write operations
57       in the list.
58

ATTRIBUTES

60   collection (required)
61       The MongoDB::Collection where the operations are to be performed.
62
63   ordered (required)
64       A boolean for whether or not operations should be ordered (true) or
65       unordered (false).
66
67   bypassDocumentValidation
68       A boolean for whether or not operations should bypass document
69       validation.  Default is false.
70

METHODS

72   find
73           $view = $bulk->find( $query_document );
74
75       The "find" method returns a MongoDB::BulkWriteView object that allows
76       write operations like "update" or "remove", constrained by a query
77       document.
78
79       A query document is required.  Use an empty hashref for no criteria:
80
81           $bulk->find( {} )->remove; # remove all documents!
82
83       An exception will be thrown on error.
84
85   insert_one
86           $bulk->insert_one( $doc );
87
88       Queues a document for insertion when "execute" is called.  The document
89       may be a hash reference, an array reference (with balanced key/value
90       pairs) or a Tie::IxHash object.  If the document does not have an "_id"
91       field, one will be added to the original.
92
93       The method has an empty return on success; an exception will be thrown
94       on error.
95
96   execute
97           my $result = $bulk->execute;
98           # Optional write concern:
99           my $result = $bulk->execute( $concern );
100           # With options
101           my $result = $bulk->execute( $concern, $options );
102
103       Executes the queued operations.  The order and semantics depend on
104       whether the bulk object is ordered or unordered:
105
106       •   ordered — operations are executed in order, but operations of the
107           same type (e.g. multiple inserts) may be grouped together and sent
108           to the server.  If the server returns an error, the bulk operation
109           will stop and an error will be thrown.
110
111       •   unordered — operations are grouped by type and sent to the server
112           in an unpredictable order.  After all operations are sent, if any
113           errors occurred, an error will be thrown.
114
115       When grouping operations of a type, operations will be sent to the
116       server in batches not exceeding 16MiB or 1000 items (for a version 2.6
117       or later server) or individually (for legacy servers without write
118       command support).
119
120       A write concern is optional, and can either take a pre-constructed
121       WriteConcern object, or the arguments to construct one.  For
122       information on write concerns, see MongoDB::WriteConcern.
123
124       The options argument is an optional hashref which can contain the
125       following values:
126
127       •   "session" - the session to use for these operations. If not
128           supplied, will use an implicit session. For more information see
129           MongoDB::ClientSession
130
131       This method returns a MongoDB::BulkWriteResult object if the bulk
132       operation executes successfully.
133
134       Typical errors might include:
135
136       •   "MongoDB::WriteError" — one or more write operations failed
137
138       •   "MongoDB::WriteConcernError" - all writes were accepted by a
139           primary, but the write concern failed
140
141       •   "MongoDB::DatabaseError" — a command to the database failed
142           entirely
143
144       See MongoDB::Error for more on error handling.
145
146       NOTE: it is an error to call "execute" without any operations or to
147       call "execute" more than once on the same bulk object.
148

AUTHORS

150       •   David Golden <david@mongodb.com>
151
152       •   Rassi <rassi@mongodb.com>
153
154       •   Mike Friedman <friedo@friedo.com>
155
156       •   Kristina Chodorow <k.chodorow@gmail.com>
157
158       •   Florian Ragwitz <rafl@debian.org>
159

161       This software is Copyright (c) 2020 by MongoDB, Inc.
162
163       This is free software, licensed under:
164
165         The Apache License, Version 2.0, January 2004
166
167
168
169perl v5.34.0                      2022-01-21             MongoDB::BulkWrite(3)
Impressum