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 #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  */
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  */
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  */
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  */
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  */
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
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_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)
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)
bool(* aerospike_scan_foreach_callback)(const as_val *val, void *udata)