All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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 /**
20  * @defgroup scan_operations Scan Operations
21  * @ingroup client_operations
22  *
23  * Aerospike Scan Operations provide the ability to scan all record of a
24  * namespace and set in an Aerospike database.
25  *
26  * ## Usage
27  *
28  * Before you can execute a scan, you first need to define a scan using
29  * as_scan. See as_scan for details on defining scans.
30  *
31  * Once you have a scan defined, then you can execute the scan
32  * using either:
33  *
34  * - aerospike_scan_foreach() — Execute a scan on the database, then process
35  * the results.
36  * - aerospike_scan_background() — Send a scan to the database, and not wait
37  * for completed. The scan is given an id, which can be used to query the
38  * scan status.
39  *
40  * When aerospike_scan_foreach() is executed, it will process the results
41  * and create records on the stack. Because the records are on the stack,
42  * they will only be available within the context of the callback function.
43  *
44  * When aerospike_scan_background() is executed, the client will not wait for
45  * results from the database. Instead, the client will be given a scan_id,
46  * which can be used to query the scan status on the database via
47  * aerospike_scan_info().
48  *
49  * ## Walk-through
50  *
51  * First, we build a scan using as_scan. The scan will be on the "test"
52  * namespace and "demo" set. We will select only bins "a" and "b" to be returned
53  * for each record.
54  *
55  * ~~~~~~~~~~{.c}
56  * as_scan scan;
57  * as_scan_init(&scan, "test", "demo");
58  *
59  * as_scan_select_inita(&scan, 2);
60  * as_scan_select(&scan, "a");
61  * as_scan_select(&scan, "B");
62  * ~~~~~~~~~~
63  *
64  * Now that we have a scan defined, we want to execute it using
65  * aerospike_scan_foreach().
66  *
67  * ~~~~~~~~~~{.c}
68  * if ( aerospike_scan_foreach(&as, &err, NULL, &scan, callback, NULL) != AEROSPIKE_OK ) {
69  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
70  * }
71  * ~~~~~~~~~~
72  *
73  * The callback provided to the function above is implemented as:
74  *
75  * ~~~~~~~~~~{.c}
76  * bool callback(const as_val * val, void * udata) {
77  * as_record * rec = as_record_fromval(val);
78  * if ( !rec ) return false;
79  * fprintf("record contains %d bins", as_record_numbins(rec));
80  * return true;
81  * }
82  * ~~~~~~~~~~
83  *
84  * An as_scan is simply a scan definition, so it does not contain any state,
85  * allowing it to be reused for multiple scan operations.
86  *
87  * When you are finished with the scan, you should destroy the resources
88  * allocated to it:
89  *
90  * ~~~~~~~~~~{.c}
91  * as_scan_destroy(&scan);
92  * ~~~~~~~~~~
93  */
94 
95 #include <aerospike/aerospike.h>
96 #include <aerospike/as_error.h>
97 #include <aerospike/as_policy.h>
98 #include <aerospike/as_scan.h>
99 #include <aerospike/as_status.h>
100 #include <aerospike/as_val.h>
101 
102 #ifdef __cplusplus
103 extern "C" {
104 #endif
105 
106 /******************************************************************************
107  * TYPES
108  *****************************************************************************/
109 
110 /**
111  * This callback will be called for each value or record returned from a scan.
112  * Multiple threads will likely be calling this callback in parallel. Therefore,
113  * your callback implementation should be thread safe.
114  *
115  * The following functions accept the callback:
116  * - aerospike_scan_foreach()
117  * - aerospike_scan_node()
118  *
119  * ~~~~~~~~~~{.c}
120  * bool my_callback(const as_val * val, void * udata) {
121  * return true;
122  * }
123  * ~~~~~~~~~~
124  *
125  * @param val The value received from the query.
126  * @param udata User-data provided to the calling function.
127  *
128  * @return `true` to continue to the next value. Otherwise, iteration will end.
129  *
130  * @ingroup scan_operations
131  */
132 typedef bool (* aerospike_scan_foreach_callback)(const as_val * val, void * udata);
133 
134 /******************************************************************************
135  * FUNCTIONS
136  *****************************************************************************/
137 
138 /**
139  * Scan the records in the specified namespace and set in the cluster.
140  *
141  * Scan will be run in the background by a thread on client side.
142  * No callback will be called in this case.
143  *
144  * ~~~~~~~~~~{.c}
145  * as_scan scan;
146  * as_scan_init(&scan, "test", "demo");
147  *
148  * uint64_t scanid = 0;
149  *
150  * if ( aerospike_scan_background(&as, &err, NULL, &scan, &scanid) != AEROSPIKE_OK ) {
151  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
152  * }
153  * else {
154  * printf("Running background scan job: %ll", scanid);
155  * }
156  *
157  * as_scan_destroy(&scan);
158  * ~~~~~~~~~~
159  *
160  * The scanid can be used to query the status of the scan running in the
161  * database via aerospike_scan_info().
162  *
163  * @param as The aerospike instance to use for this operation.
164  * @param err The as_error to be populated if an error occurs.
165  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
166  * @param scan The scan to execute against the cluster.
167  * @param scan_id The id for the scan job, which can be used for querying the status of the scan.
168  *
169  * @return AEROSPIKE_OK on success. Otherwise an error occurred.
170  *
171  * @ingroup scan_operations
172  */
174  aerospike * as, as_error * err, const as_policy_scan * policy,
175  const as_scan * scan, uint64_t * scan_id
176  );
177 
178 /**
179  * Wait for a background scan to be completed by servers.
180  *
181  * ~~~~~~~~~~{.c}
182  * uint64_t scan_id = 1234;
183  * aerospike_scan_wait(&as, &err, NULL, scan_id, 0);
184  * ~~~~~~~~~~
185  *
186  * @param as The aerospike instance to use for this operation.
187  * @param err The as_error to be populated if an error occurs.
188  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
189  * @param scan_id The id for the scan job.
190  * @param interval_ms The polling interval in milliseconds. If zero, 1000 ms is used.
191  *
192  * @return AEROSPIKE_OK on success. Otherwise an error occurred.
193  */
195  aerospike * as, as_error * err, const as_policy_info * policy,
196  uint64_t scan_id, uint32_t interval_ms
197  );
198 
199 /**
200  * Check the progress of a background scan running on the database. The status
201  * of the scan running on the datatabse will be populated into an as_scan_info.
202  *
203  * ~~~~~~~~~~{.c}
204  * uint64_t scan_id = 1234;
205  * as_scan_info scan_info;
206  *
207  * if ( aerospike_scan_info(&as, &err, NULL, &scan, scan_id, &scan_info) != AEROSPIKE_OK ) {
208  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
209  * }
210  * else {
211  * printf("Scan id=%ll, status=%d percent=%d", scan_id, scan_info.status, scan_info.progress_pct);
212  * }
213  * ~~~~~~~~~~
214  *
215  *
216  * @param as The aerospike instance to use for this operation.
217  * @param err The as_error to be populated if an error occurs.
218  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
219  * @param scan_id The id for the scan job to check the status of.
220  * @param info Information about this scan, to be populated by this operation.
221  *
222  * @return AEROSPIKE_OK on success. Otherwise an error occurred.
223  *
224  * @ingroup scan_operations
225  */
227  aerospike * as, as_error * err, const as_policy_info * policy,
228  uint64_t scan_id, as_scan_info * info
229  );
230 
231 /**
232  * Scan the records in the specified namespace and set in the cluster.
233  *
234  * Call the callback function for each record scanned. When all records have
235  * been scanned, then callback will be called with a NULL value for the record.
236  *
237  * Multiple threads will likely be calling the callback in parallel. Therefore,
238  * your callback implementation should be thread safe.
239  *
240  * ~~~~~~~~~~{.c}
241  * as_scan scan;
242  * as_scan_init(&scan, "test", "demo");
243  *
244  * if ( aerospike_scan_foreach(&as, &err, NULL, &scan, callback, NULL) != AEROSPIKE_OK ) {
245  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
246  * }
247  *
248  * as_scan_destroy(&scan);
249  * ~~~~~~~~~~
250  *
251  *
252  * @param as The aerospike instance to use for this operation.
253  * @param err The as_error to be populated if an error occurs.
254  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
255  * @param scan The scan to execute against the cluster.
256  * @param callback The function to be called for each record scanned.
257  * @param udata User-data to be passed to the callback.
258  *
259  * @return AEROSPIKE_OK on success. Otherwise an error occurred.
260  *
261  * @ingroup scan_operations
262  */
264  aerospike * as, as_error * err, const as_policy_scan * policy,
265  const as_scan * scan,
266  aerospike_scan_foreach_callback callback, void * udata
267  );
268 
269 /**
270  * Scan the records in the specified namespace and set for a single node.
271  *
272  * The callback function will be called for each record scanned. When all records have
273  * been scanned, then callback will be called with a NULL value for the record.
274  *
275  * ~~~~~~~~~~{.c}
276  * char* node_names = NULL;
277  * int n_nodes = 0;
278  * as_cluster_get_node_names(as->cluster, &n_nodes, &node_names);
279  *
280  * if (n_nodes <= 0)
281  * return <error>;
282  *
283  * as_scan scan;
284  * as_scan_init(&scan, "test", "demo");
285  *
286  * if (aerospike_scan_node(&as, &err, NULL, &scan, node_names[0], callback, NULL) != AEROSPIKE_OK ) {
287  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
288  * }
289  *
290  * free(node_names);
291  * as_scan_destroy(&scan);
292  * ~~~~~~~~~~
293  *
294  * @param as The aerospike instance to use for this operation.
295  * @param err The as_error to be populated if an error occurs.
296  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
297  * @param scan The scan to execute against the cluster.
298  * @param node_name The node name to scan.
299  * @param callback The function to be called for each record scanned.
300  * @param udata User-data to be passed to the callback.
301  *
302  * @return AEROSPIKE_OK on success. Otherwise an error occurred.
303  *
304  * @ingroup scan_operations
305  */
307  aerospike * as, as_error * err, const as_policy_scan * policy,
308  const as_scan * scan, const char* node_name,
309  aerospike_scan_foreach_callback callback, void * udata
310  );
311 
312 #ifdef __cplusplus
313 } // end extern "C"
314 #endif
as_status aerospike_scan_background(aerospike *as, as_error *err, const as_policy_scan *policy, const as_scan *scan, uint64_t *scan_id)
as_status aerospike_scan_info(aerospike *as, as_error *err, const as_policy_info *policy, uint64_t scan_id, as_scan_info *info)
as_status
Definition: as_status.h:30
Definition: as_val.h:55
as_status aerospike_scan_foreach(aerospike *as, as_error *err, const as_policy_scan *policy, const as_scan *scan, aerospike_scan_foreach_callback callback, void *udata)
as_status aerospike_scan_wait(aerospike *as, as_error *err, const as_policy_info *policy, uint64_t scan_id, uint32_t interval_ms)
as_status aerospike_scan_node(aerospike *as, as_error *err, const as_policy_scan *policy, const as_scan *scan, const char *node_name, aerospike_scan_foreach_callback callback, void *udata)
bool(* aerospike_scan_foreach_callback)(const as_val *val, void *udata)