All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
aerospike_scan.h
Go to the documentation of this file.
1 /*
2  * Copyright 2008-2014 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 /******************************************************************************
103  * TYPES
104  *****************************************************************************/
105 
106 /**
107  * This callback will be called for each value or record returned from
108  * a scan.
109  *
110  * The following functions accept the callback:
111  * - aerospike_scan_foreach()
112  * - aerospike_scan_node_foreach()
113  *
114  * ~~~~~~~~~~{.c}
115  * bool my_callback(const as_val * val, void * udata) {
116  * return true;
117  * }
118  * ~~~~~~~~~~
119  *
120  * @param val The value received from the query.
121  * @param udata User-data provided to the calling function.
122  *
123  * @return `true` to continue to the next value. Otherwise, iteration will end.
124  *
125  * @ingroup scan_operations
126  */
127 typedef bool (* aerospike_scan_foreach_callback)(const as_val * val, void * udata);
128 
129 /******************************************************************************
130  * FUNCTIONS
131  *****************************************************************************/
132 
133 /**
134  * Scan the records in the specified namespace and set in the cluster.
135  *
136  * Scan will be run in the background by a thread on client side.
137  * No callback will be called in this case.
138  *
139  * ~~~~~~~~~~{.c}
140  * as_scan scan;
141  * as_scan_init(&scan, "test", "demo");
142  *
143  * uint64_t scanid = 0;
144  *
145  * if ( aerospike_scan_background(&as, &err, NULL, &scan, &scanid) != AEROSPIKE_OK ) {
146  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
147  * }
148  * else {
149  * printf("Running background scan job: %ll", scanid);
150  * }
151  *
152  * as_scan_destroy(&scan);
153  * ~~~~~~~~~~
154  *
155  * The scanid can be used to query the status of the scan running in the
156  * database via aerospike_scan_info().
157  *
158  * @param as The aerospike instance to use for this operation.
159  * @param err The as_error to be populated if an error occurs.
160  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
161  * @param scan The scan to execute against the cluster.
162  * @param scan_id The id for the scan job, which can be used for querying the status of the scan.
163  *
164  * @return AEROSPIKE_OK on success. Otherwise an error occurred.
165  *
166  * @ingroup scan_operations
167  */
169  aerospike * as, as_error * err, const as_policy_scan * policy,
170  const as_scan * scan, uint64_t * scan_id
171  );
172 
173 /**
174  * Wait for a background scan to be completed by servers.
175  *
176  * ~~~~~~~~~~{.c}
177  * uint64_t scan_id = 1234;
178  * aerospike_scan_wait(&as, &err, NULL, scan_id, 0);
179  * ~~~~~~~~~~
180  *
181  * @param as The aerospike instance to use for this operation.
182  * @param err The as_error to be populated if an error occurs.
183  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
184  * @param scan_id The id for the scan job.
185  * @param interval_ms The polling interval in milliseconds. If zero, 1000 ms is used.
186  *
187  * @return AEROSPIKE_OK on success. Otherwise an error occurred.
188  */
190  aerospike * as, as_error * err, const as_policy_info * policy,
191  uint64_t scan_id, uint32_t interval_ms
192  );
193 
194 /**
195  * Check the progress of a background scan running on the database. The status
196  * of the scan running on the datatabse will be populated into an as_scan_info.
197  *
198  * ~~~~~~~~~~{.c}
199  * uint64_t scan_id = 1234;
200  * as_scan_info scan_info;
201  *
202  * if ( aerospike_scan_info(&as, &err, NULL, &scan, scan_id, &scan_info) != AEROSPIKE_OK ) {
203  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
204  * }
205  * else {
206  * printf("Scan id=%ll, status=%d percent=%d", scan_id, scan_info.status, scan_info.progress_pct);
207  * }
208  * ~~~~~~~~~~
209  *
210  *
211  * @param as The aerospike instance to use for this operation.
212  * @param err The as_error to be populated if an error occurs.
213  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
214  * @param scan_id The id for the scan job to check the status of.
215  * @param info Information about this scan, to be populated by this operation.
216  *
217  * @return AEROSPIKE_OK on success. Otherwise an error occurred.
218  *
219  * @ingroup scan_operations
220  */
222  aerospike * as, as_error * err, const as_policy_info * policy,
223  uint64_t scan_id, as_scan_info * info
224  );
225 
226 /**
227  * Scan the records in the specified namespace and set in the cluster.
228  *
229  * Call the callback function for each record scanned. When all records have
230  * been scanned, then callback will be called with a NULL value for the record.
231  *
232  * ~~~~~~~~~~{.c}
233  * as_scan scan;
234  * as_scan_init(&scan, "test", "demo");
235  *
236  * if ( aerospike_scan_foreach(&as, &err, NULL, &scan, callback, NULL) != AEROSPIKE_OK ) {
237  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
238  * }
239  *
240  * as_scan_destroy(&scan);
241  * ~~~~~~~~~~
242  *
243  *
244  * @param as The aerospike instance to use for this operation.
245  * @param err The as_error to be populated if an error occurs.
246  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
247  * @param scan The scan to execute against the cluster.
248  * @param callback The function to be called for each record scanned.
249  * @param udata User-data to be passed to the callback.
250  *
251  * @return AEROSPIKE_OK on success. Otherwise an error occurred.
252  *
253  * @ingroup scan_operations
254  */
256  aerospike * as, as_error * err, const as_policy_scan * policy,
257  const as_scan * scan,
258  aerospike_scan_foreach_callback callback, void * udata
259  );
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:26
Definition: as_val.h:51
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)