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-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  * Check the progress of a background scan running on the database. The status
175  * of the scan running on the datatabse will be populated into an as_scan_info.
176  *
177  * ~~~~~~~~~~{.c}
178  * uint64_t scan_id = 1234;
179  * as_scan_info scan_info;
180  *
181  * if ( aerospike_scan_info(&as, &err, NULL, &scan, scan_id, &scan_info) != AEROSPIKE_OK ) {
182  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
183  * }
184  * else {
185  * printf("Scan id=%ll, status=%d percent=%d", scan_id, scan_info.status, scan_info.progress_pct);
186  * }
187  * ~~~~~~~~~~
188  *
189  *
190  * @param as The aerospike instance to use for this operation.
191  * @param err The as_error to be populated if an error occurs.
192  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
193  * @param scan_id The id for the scan job to check the status of.
194  * @param info Information about this scan, to be populated by this operation.
195  *
196  * @return AEROSPIKE_OK on success. Otherwise an error occurred.
197  *
198  * @ingroup scan_operations
199  */
201  aerospike * as, as_error * err, const as_policy_info * policy,
202  uint64_t scan_id, as_scan_info * info
203  );
204 
205 /**
206  * Scan the records in the specified namespace and set in the cluster.
207  *
208  * Call the callback function for each record scanned. When all records have
209  * been scanned, then callback will be called with a NULL value for the record.
210  *
211  * ~~~~~~~~~~{.c}
212  * as_scan scan;
213  * as_scan_init(&scan, "test", "demo");
214  *
215  * if ( aerospike_scan_foreach(&as, &err, NULL, &scan, callback, NULL) != AEROSPIKE_OK ) {
216  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
217  * }
218  *
219  * as_scan_destroy(&scan);
220  * ~~~~~~~~~~
221  *
222  *
223  * @param as The aerospike instance to use for this operation.
224  * @param err The as_error to be populated if an error occurs.
225  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
226  * @param scan The scan to execute against the cluster.
227  * @param callback The function to be called for each record scanned.
228  * @param udata User-data to be passed to the callback.
229  *
230  * @return AEROSPIKE_OK on success. Otherwise an error occurred.
231  *
232  * @ingroup scan_operations
233  */
235  aerospike * as, as_error * err, const as_policy_scan * policy,
236  const as_scan * scan,
237  aerospike_scan_foreach_callback callback, void * udata
238  );
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)
bool(* aerospike_scan_foreach_callback)(const as_val *val, void *udata)