Main Page
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Friends
Macros
Groups
Pages
aerospike
aerospike_scan.h
Go to the documentation of this file.
1
/*
2
* Copyright 2008-2015 Aerospike, Inc.
3
*
4
* Portions may be licensed to Aerospike, Inc. under one or more contributor
5
* license agreements.
6
*
7
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
8
* use this file except in compliance with the License. You may obtain a copy of
9
* the License at http://www.apache.org/licenses/LICENSE-2.0
10
*
11
* Unless required by applicable law or agreed to in writing, software
12
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
14
* License for the specific language governing permissions and limitations under
15
* the License.
16
*/
17
#pragma once
18
19
#ifdef __cplusplus
20
extern
"C"
{
21
#endif
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
#include <
aerospike/aerospike.h
>
100
#include <
aerospike/as_error.h
>
101
#include <
aerospike/as_policy.h
>
102
#include <
aerospike/as_scan.h
>
103
#include <
aerospike/as_status.h
>
104
#include <
aerospike/as_val.h
>
105
106
/******************************************************************************
107
* TYPES
108
*****************************************************************************/
109
110
/**
111
* This callback will be called for each value or record returned from
112
* a scan.
113
*
114
* The following functions accept the callback:
115
* - aerospike_scan_foreach()
116
* - aerospike_scan_node_foreach()
117
*
118
* ~~~~~~~~~~{.c}
119
* bool my_callback(const as_val * val, void * udata) {
120
* return true;
121
* }
122
* ~~~~~~~~~~
123
*
124
* @param val The value received from the query.
125
* @param udata User-data provided to the calling function.
126
*
127
* @return `true` to continue to the next value. Otherwise, iteration will end.
128
*
129
* @ingroup scan_operations
130
*/
131
typedef
bool (*
aerospike_scan_foreach_callback
)(
const
as_val
* val,
void
* udata);
132
133
/******************************************************************************
134
* FUNCTIONS
135
*****************************************************************************/
136
137
/**
138
* Scan the records in the specified namespace and set in the cluster.
139
*
140
* Scan will be run in the background by a thread on client side.
141
* No callback will be called in this case.
142
*
143
* ~~~~~~~~~~{.c}
144
* as_scan scan;
145
* as_scan_init(&scan, "test", "demo");
146
*
147
* uint64_t scanid = 0;
148
*
149
* if ( aerospike_scan_background(&as, &err, NULL, &scan, &scanid) != AEROSPIKE_OK ) {
150
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
151
* }
152
* else {
153
* printf("Running background scan job: %ll", scanid);
154
* }
155
*
156
* as_scan_destroy(&scan);
157
* ~~~~~~~~~~
158
*
159
* The scanid can be used to query the status of the scan running in the
160
* database via aerospike_scan_info().
161
*
162
* @param as The aerospike instance to use for this operation.
163
* @param err The as_error to be populated if an error occurs.
164
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
165
* @param scan The scan to execute against the cluster.
166
* @param scan_id The id for the scan job, which can be used for querying the status of the scan.
167
*
168
* @return AEROSPIKE_OK on success. Otherwise an error occurred.
169
*
170
* @ingroup scan_operations
171
*/
172
as_status
aerospike_scan_background
(
173
aerospike
* as,
as_error
* err,
const
as_policy_scan
* policy,
174
const
as_scan
* scan, uint64_t * scan_id
175
);
176
177
/**
178
* Wait for a background scan to be completed by servers.
179
*
180
* ~~~~~~~~~~{.c}
181
* uint64_t scan_id = 1234;
182
* aerospike_scan_wait(&as, &err, NULL, scan_id, 0);
183
* ~~~~~~~~~~
184
*
185
* @param as The aerospike instance to use for this operation.
186
* @param err The as_error to be populated if an error occurs.
187
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
188
* @param scan_id The id for the scan job.
189
* @param interval_ms The polling interval in milliseconds. If zero, 1000 ms is used.
190
*
191
* @return AEROSPIKE_OK on success. Otherwise an error occurred.
192
*/
193
as_status
aerospike_scan_wait
(
194
aerospike
* as,
as_error
* err,
const
as_policy_info
* policy,
195
uint64_t scan_id, uint32_t interval_ms
196
);
197
198
/**
199
* Check the progress of a background scan running on the database. The status
200
* of the scan running on the datatabse will be populated into an as_scan_info.
201
*
202
* ~~~~~~~~~~{.c}
203
* uint64_t scan_id = 1234;
204
* as_scan_info scan_info;
205
*
206
* if ( aerospike_scan_info(&as, &err, NULL, &scan, scan_id, &scan_info) != AEROSPIKE_OK ) {
207
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
208
* }
209
* else {
210
* printf("Scan id=%ll, status=%d percent=%d", scan_id, scan_info.status, scan_info.progress_pct);
211
* }
212
* ~~~~~~~~~~
213
*
214
*
215
* @param as The aerospike instance to use for this operation.
216
* @param err The as_error to be populated if an error occurs.
217
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
218
* @param scan_id The id for the scan job to check the status of.
219
* @param info Information about this scan, to be populated by this operation.
220
*
221
* @return AEROSPIKE_OK on success. Otherwise an error occurred.
222
*
223
* @ingroup scan_operations
224
*/
225
as_status
aerospike_scan_info
(
226
aerospike
* as,
as_error
* err,
const
as_policy_info
* policy,
227
uint64_t scan_id,
as_scan_info
* info
228
);
229
230
/**
231
* Scan the records in the specified namespace and set in the cluster.
232
*
233
* Call the callback function for each record scanned. When all records have
234
* been scanned, then callback will be called with a NULL value for the record.
235
*
236
* ~~~~~~~~~~{.c}
237
* as_scan scan;
238
* as_scan_init(&scan, "test", "demo");
239
*
240
* if ( aerospike_scan_foreach(&as, &err, NULL, &scan, callback, NULL) != AEROSPIKE_OK ) {
241
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
242
* }
243
*
244
* as_scan_destroy(&scan);
245
* ~~~~~~~~~~
246
*
247
*
248
* @param as The aerospike instance to use for this operation.
249
* @param err The as_error to be populated if an error occurs.
250
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
251
* @param scan The scan to execute against the cluster.
252
* @param callback The function to be called for each record scanned.
253
* @param udata User-data to be passed to the callback.
254
*
255
* @return AEROSPIKE_OK on success. Otherwise an error occurred.
256
*
257
* @ingroup scan_operations
258
*/
259
as_status
aerospike_scan_foreach
(
260
aerospike
* as,
as_error
* err,
const
as_policy_scan
* policy,
261
const
as_scan
* scan,
262
aerospike_scan_foreach_callback
callback,
void
* udata
263
);
264
265
/**
266
* Scan the records in the specified namespace and set for a single node.
267
*
268
* The callback function will be called for each record scanned. When all records have
269
* been scanned, then callback will be called with a NULL value for the record.
270
*
271
* ~~~~~~~~~~{.c}
272
* char* node_names = NULL;
273
* int n_nodes = 0;
274
* as_cluster_get_node_names(as->cluster, &n_nodes, &node_names);
275
*
276
* if (n_nodes <= 0)
277
* return <error>;
278
*
279
* as_scan scan;
280
* as_scan_init(&scan, "test", "demo");
281
*
282
* if (aerospike_scan_node(&as, &err, NULL, &scan, node_names[0], callback, NULL) != AEROSPIKE_OK ) {
283
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
284
* }
285
*
286
* free(node_names);
287
* as_scan_destroy(&scan);
288
* ~~~~~~~~~~
289
*
290
* @param as The aerospike instance to use for this operation.
291
* @param err The as_error to be populated if an error occurs.
292
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
293
* @param scan The scan to execute against the cluster.
294
* @param node_name The node name to scan.
295
* @param callback The function to be called for each record scanned.
296
* @param udata User-data to be passed to the callback.
297
*
298
* @return AEROSPIKE_OK on success. Otherwise an error occurred.
299
*/
300
as_status
aerospike_scan_node
(
301
aerospike
* as,
as_error
* err,
const
as_policy_scan
* policy,
302
const
as_scan
* scan,
const
char
* node_name,
303
aerospike_scan_foreach_callback
callback,
void
* udata
304
);
305
306
#ifdef __cplusplus
307
}
// end extern "C"
308
#endif