1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
NAME
Catmandu::Store::MongoDB - A searchable store backed by MongoDB
SYNOPSIS
# On the command line
$ catmandu import -v JSON --multiline 1 to MongoDB --database_name bibliography --bag books < books.json
$ catmandu export MongoDB --database_name bibliography --bag books to YAML
$ catmandu count MongoDB --database_name bibliography --bag books --query '{"PublicationYear": "1937"}'
$ catmandu count MongoDB --database_name bibliography --bag books --query '{"Author": "Jones"}' --sort '{"PublicationYear":1}'
# In perl
use Catmandu::Store::MongoDB;
my $store = Catmandu::Store::MongoDB->new(database_name => 'test');
my $obj1 = $store->bag->add({ name => 'Patrick' });
printf "obj1 stored as %s\n" , $obj1->{_id};
# Force an id in the store
my $obj2 = $store->bag->add({ _id => 'test123' , name => 'Nicolas' });
my $obj3 = $store->bag->get('test123');
$store->bag->delete('test123');
$store->bag->delete_all;
# All bags are iterators
$store->bag->each(sub { ... });
$store->bag->take(10)->each(sub { ... });
# Search
my $hits = $store->bag->search(query => '{"name":"Patrick"}');
my $hits = $store->bag->search(query => '{"name":"Patrick"}' , sort => { age => -1} );
my $hits = $store->bag->search(query => {name => "Patrick"} , start => 0 , limit => 100);
my $hits = $store->bag->search(query => {name => "Patrick"} , fields => {_id => 0, name => 1});
my $next_page = $hits->next_page;
my $hits = $store->bag->search(query => '{"name":"Patrick"}' , page => $next_page);
my $iterator = $store->bag->searcher(query => {name => "Patrick"});
my $iterator = $store->bag->searcher(query => {name => "Patrick"}, fields => {_id => 0, name => 1});
# Catmandu::Store::MongoDB supports CQL...
my $hits = $store->bag->search(cql_query => 'name any "Patrick"');
DESCRIPTION
A Catmandu::Store::MongoDB is a Perl package that can store data into
MongoDB databases. The database as a whole is called a 'store'.
Databases also have compartments (e.g. tables) called Catmandu::Bag-s.
CONFIGURATION
database_name
MongoDB database name.
estimate_count
Use a faster estimated collection document count if true.
All other options are passed on to the MongoDB client.
METHODS
new(database_name => $name, %connection_opts)
new(database_name => $name , bags => { data => { cql_mapping =>
$cql_mapping } })
Create a new Catmandu::Store::MongoDB store with name $name. Optionally
provide connection parameters (see MongoDB::MongoClient for possible
options).
The store supports CQL searches when a cql_mapping is provided. This
hash contains a translation of CQL fields into MongoDB searchable
fields.
# Example mapping
$cql_mapping = {
indexes => {
title => {
op => {
'any' => 1 ,
'all' => 1 ,
'=' => 1 ,
'<>' => 1 ,
'exact' => {field => [qw(mytitle.exact myalttitle.exact)]}
} ,
sort => 1,
field => 'mytitle',
cb => ['Biblio::Search', 'normalize_title']
}
}
}
The CQL mapping above will support for the 'title' field the CQL
operators: any, all, =, <> and exact.
The 'title' field will be mapped into the MongoDB field 'mytitle',
except for the 'exact' operator. In case of 'exact' both the
'mytitle.exact' and 'myalttitle.exact' fields will be searched.
The CQL mapping allows for sorting on the 'title' field. If, for
instance, we would like to use a special MongoDB field for sorting we
could have written "sort => { field => 'mytitle.sort' }".
The CQL has an optional callback field 'cb' which contains a reference
to subroutines to rewrite or augment the search query. In this case, in
the Biblio::Search package contains a normalize_title subroutine which
returns a string or an ARRAY of string with augmented title(s). E.g.
package Biblio::Search;
sub normalize_title {
my ($self,$title) = @_;
# delete all bad characters
my $new_title =~ s{[^A-Z0-9]+}{}g;
$new_title;
}
1;
bag($name)
Create or retieve a bag with name $name. Returns a Catmandu::Bag.
client
Return the MongoDB::MongoClient instance.
database
Return a MongoDB::Database instance.
drop
Delete the store and all it's bags.
transaction(\&sub)
Execute $sub within a transaction. See Catmandu::Transactional.
Note that only MongoDB databases with feature compatibility >= 4.0 and
in a replica set have support for transactions. See
https://docs.mongodb.com/manual/reference/command/setFeatureCompatibilityVersion/#view-fcv
and
https://docs.mongodb.com/manual/tutorial/convert-standalone-to-replica-set/
for more info.
Search
Search the database: see Catmandu::Searchable and
Catmandu::CQLSearchable. This module supports an additional search
parameter:
- fields => { <field> => <0|1> } : limit fields to return from a query (see L<MongoDB Tutorial|https://docs.mongodb.org/manual/tutorial/project-fields-from-query-results/>)
SEE ALSO
Catmandu::Bag, Catmandu::CQLSearchable, Catmandu::Droppable,
Catmandu::Transactional, MongoDB::MongoClient
AUTHOR
Nicolas Steenlant, <nicolas.steenlant at ugent.be>
CONTRIBUTORS
Johann Rolschewski, <jorol at cpan.org>
LICENSE AND COPYRIGHT
This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.
|
