Main Page
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Friends
Macros
Groups
Pages
src
include
aerospike
src/include/aerospike/aerospike_scan.h
Go to the documentation of this file.
1
/******************************************************************************
2
* Copyright 2008-2013 by Aerospike.
3
*
4
* Permission is hereby granted, free of charge, to any person obtaining a copy
5
* of this software and associated documentation files (the "Software"), to
6
* deal in the Software without restriction, including without limitation the
7
* rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
8
* sell copies of the Software, and to permit persons to whom the Software is
9
* furnished to do so, subject to the following conditions:
10
*
11
* The above copyright notice and this permission notice shall be included in
12
* all copies or substantial portions of the Software.
13
*
14
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
19
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
20
* IN THE SOFTWARE.
21
*****************************************************************************/
22
23
/**
24
* @defgroup scan_operations Scan Operations
25
* @ingroup client_operations
26
*
27
* Aerospike Scan Operations provide the ability to scan all record of a
28
* namespace and set in an Aerospike database.
29
*
30
* ## Usage
31
*
32
* Before you can execute a scan, you first need to define a scan using
33
* as_scan. See as_scan for details on defining scans.
34
*
35
* Once you have a scan defined, then you can execute the scan
36
* using either:
37
*
38
* - aerospike_scan_foreach() — Execute a scan on the database, then process
39
* the results.
40
* - aerospike_scan_background() — Send a scan to the database, and not wait
41
* for completed. The scan is given an id, which can be used to query the
42
* scan status.
43
*
44
* When aerospike_scan_foreach() is executed, it will process the results
45
* and create records on the stack. Because the records are on the stack,
46
* they will only be available within the context of the callback function.
47
*
48
* When aerospike_scan_background() is executed, the client will not wait for
49
* results from the database. Instead, the client will be given a scan_id,
50
* which can be used to query the scan status on the database via
51
* aerospike_scan_info().
52
*
53
* ## Walk-through
54
*
55
* First, we build a scan using as_scan. The scan will be on the "test"
56
* namespace and "demo" set. We will select only bins "a" and "b" to be returned
57
* for each record.
58
*
59
* ~~~~~~~~~~{.c}
60
* as_scan scan;
61
* as_scan_init(&scan, "test", "demo");
62
*
63
* as_scan_select_inita(&scan, 2);
64
* as_scan_select(&scan, "a");
65
* as_scan_select(&scan, "B");
66
* ~~~~~~~~~~
67
*
68
* Now that we have a scan defined, we want to execute it using
69
* aerospike_scan_foreach().
70
*
71
* ~~~~~~~~~~{.c}
72
* if ( aerospike_scan_foreach(&as, &err, NULL, &scan, callback, NULL) != AEROSPIKE_OK ) {
73
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
74
* }
75
* ~~~~~~~~~~
76
*
77
* The callback provided to the function above is implemented as:
78
*
79
* ~~~~~~~~~~{.c}
80
* bool callback(const as_val * val, void * udata) {
81
* as_record * rec = as_record_fromval(val);
82
* if ( !rec ) return false;
83
* fprintf("record contains %d bins", as_record_numbins(rec));
84
* return true;
85
* }
86
* ~~~~~~~~~~
87
*
88
* An as_scan is simply a scan definition, so it does not contain any state,
89
* allowing it to be reused for multiple scan operations.
90
*
91
* When you are finished with the scan, you should destroy the resources
92
* allocated to it:
93
*
94
* ~~~~~~~~~~{.c}
95
* as_scan_destroy(&scan);
96
* ~~~~~~~~~~
97
*/
98
99
#pragma once
100
101
#include <aerospike/aerospike.h>
102
#include <aerospike/as_error.h>
103
#include <aerospike/as_policy.h>
104
#include <aerospike/as_scan.h>
105
#include <aerospike/as_status.h>
106
#include <aerospike/as_val.h>
107
108
/******************************************************************************
109
* TYPES
110
*****************************************************************************/
111
112
/**
113
* This callback will be called for each value or record returned from
114
* a scan.
115
*
116
* The following functions accept the callback:
117
* - aerospike_scan_foreach()
118
* - aerospike_scan_node_foreach()
119
*
120
* ~~~~~~~~~~{.c}
121
* bool my_callback(const as_val * val, void * udata) {
122
* return true;
123
* }
124
* ~~~~~~~~~~
125
*
126
* @param val The value received from the query.
127
* @param udata User-data provided to the calling function.
128
*
129
* @return `true` to continue to the next value. Otherwise, iteration will end.
130
*
131
* @ingroup scan_operations
132
*/
133
typedef
bool (*
aerospike_scan_foreach_callback
)(
const
as_val
* val,
void
* udata);
134
135
/******************************************************************************
136
* FUNCTIONS
137
*****************************************************************************/
138
139
/**
140
* Scan the records in the specified namespace and set in the cluster.
141
*
142
* Scan will be run in the background by a thread on client side.
143
* No callback will be called in this case.
144
*
145
* ~~~~~~~~~~{.c}
146
* as_scan scan;
147
* as_scan_init(&scan, "test", "demo");
148
*
149
* uint64_t scanid = 0;
150
*
151
* if ( aerospike_scan_background(&as, &err, NULL, &scan, &scanid) != AEROSPIKE_OK ) {
152
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
153
* }
154
* else {
155
* printf("Running background scan job: %ll", scanid);
156
* }
157
*
158
* as_scan_destroy(&scan);
159
* ~~~~~~~~~~
160
*
161
* The scanid can be used to query the status of the scan running in the
162
* database via aerospike_scan_info().
163
*
164
* @param as The aerospike instance to use for this operation.
165
* @param err The as_error to be populated if an error occurs.
166
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
167
* @param scan The scan to execute against the cluster.
168
* @param scan_id The id for the scan job, which can be used for querying the status of the scan.
169
*
170
* @return AEROSPIKE_OK on success. Otherwise an error occurred.
171
*
172
* @ingroup scan_operations
173
*/
174
as_status
aerospike_scan_background
(
175
aerospike
* as,
as_error
* err,
const
as_policy_scan
* policy,
176
const
as_scan
* scan, uint64_t * scan_id
177
);
178
179
/**
180
* Check the progress of a background scan running on the database. The status
181
* of the scan running on the datatabse will be populated into an as_scan_info.
182
*
183
* ~~~~~~~~~~{.c}
184
* uint64_t scan_id = 1234;
185
* as_scan_info scan_info;
186
*
187
* if ( aerospike_scan_info(&as, &err, NULL, &scan, scan_id, &scan_info) != AEROSPIKE_OK ) {
188
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
189
* }
190
* else {
191
* printf("Scan id=%ll, status=%d percent=%d", scan_id, scan_info.status, scan_info.progress_pct);
192
* }
193
* ~~~~~~~~~~
194
*
195
*
196
* @param as The aerospike instance to use for this operation.
197
* @param err The as_error to be populated if an error occurs.
198
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
199
* @param scan_id The id for the scan job to check the status of.
200
* @param info Information about this scan, to be populated by this operation.
201
*
202
* @return AEROSPIKE_OK on success. Otherwise an error occurred.
203
*
204
* @ingroup scan_operations
205
*/
206
as_status
aerospike_scan_info
(
207
aerospike
* as,
as_error
* err,
const
as_policy_info
* policy,
208
uint64_t scan_id,
as_scan_info
*
info
209
);
210
211
/**
212
* Scan the records in the specified namespace and set in the cluster.
213
*
214
* Call the callback function for each record scanned. When all records have
215
* been scanned, then callback will be called with a NULL value for the record.
216
*
217
* ~~~~~~~~~~{.c}
218
* as_scan scan;
219
* as_scan_init(&scan, "test", "demo");
220
*
221
* if ( aerospike_scan_foreach(&as, &err, NULL, &scan, callback, NULL) != AEROSPIKE_OK ) {
222
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
223
* }
224
*
225
* as_scan_destroy(&scan);
226
* ~~~~~~~~~~
227
*
228
*
229
* @param as The aerospike instance to use for this operation.
230
* @param err The as_error to be populated if an error occurs.
231
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
232
* @param scan The scan to execute against the cluster.
233
* @param callback The function to be called for each record scanned.
234
* @param udata User-data to be passed to the callback.
235
*
236
* @return AEROSPIKE_OK on success. Otherwise an error occurred.
237
*
238
* @ingroup scan_operations
239
*/
240
as_status
aerospike_scan_foreach
(
241
aerospike
* as,
as_error
* err,
const
as_policy_scan
* policy,
242
const
as_scan
* scan,
243
aerospike_scan_foreach_callback
callback,
void
* udata
244
);