All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
target/Linux-x86_64/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  */
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  */
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  */
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  );