Main Page
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Friends
Macros
Groups
Pages
target
Linux-x86_64
include
aerospike
target/Linux-x86_64/include/aerospike/as_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
#pragma once
24
#pragma GCC diagnostic ignored "-Waddress"
25
26
#include <aerospike/as_bin.h>
27
#include <aerospike/as_key.h>
28
#include <aerospike/as_udf.h>
29
30
/******************************************************************************
31
* MACROS
32
*****************************************************************************/
33
34
/**
35
* Default value for as_scan.priority
36
*/
37
#define AS_SCAN_PRIORITY_DEFAULT AS_SCAN_PRIORITY_AUTO
38
39
/**
40
* Default value for as_scan.percent
41
*/
42
#define AS_SCAN_PERCENT_DEFAULT 100
43
44
/**
45
* Default value for as_scan.no_bins
46
*/
47
#define AS_SCAN_NOBINS_DEFAULT false
48
49
/**
50
* Default value for as_scan.concurrent
51
*/
52
#define AS_SCAN_CONCURRENT_DEFAULT false
53
54
/******************************************************************************
55
* TYPES
56
*****************************************************************************/
57
58
/**
59
* Priority levels for a scan operation.
60
*/
61
typedef
enum
as_scan_priority_e {
62
63
/**
64
* The cluster will auto adjust the scan priority.
65
*/
66
AS_SCAN_PRIORITY_AUTO
,
67
68
/**
69
* Low priority scan.
70
*/
71
AS_SCAN_PRIORITY_LOW
,
72
73
/**
74
* Medium priority scan.
75
*/
76
AS_SCAN_PRIORITY_MEDIUM
,
77
78
/**
79
* High priority scan.
80
*/
81
AS_SCAN_PRIORITY_HIGH
82
83
}
as_scan_priority
;
84
85
/**
86
* The status of a particular background scan.
87
*/
88
typedef
enum
as_scan_status_e {
89
90
/**
91
* The scan status is undefined.
92
* This is likely due to the status not being properly checked.
93
*/
94
AS_SCAN_STATUS_UNDEF
,
95
96
/**
97
* The scan is currently running.
98
*/
99
AS_SCAN_STATUS_INPROGRESS
,
100
101
/**
102
* The scan was aborted. Due to failure or the user.
103
*/
104
AS_SCAN_STATUS_ABORTED
,
105
106
/**
107
* The scan completed successfully.
108
*/
109
AS_SCAN_STATUS_COMPLETED
,
110
111
}
as_scan_status
;
112
113
/**
114
* Information about a particular background scan.
115
*
116
* @ingroup as_scan_object
117
*/
118
typedef
struct
as_scan_info_s {
119
120
/**
121
* Status of the scan.
122
*/
123
as_scan_status
status;
124
125
/**
126
* Progress estimate for the scan, as percentage.
127
*/
128
uint32_t progress_pct;
129
130
/**
131
* How many records have been scanned.
132
*/
133
uint32_t records_scanned;
134
135
}
as_scan_info
;
136
137
/**
138
* Sequence of bins which should be selected during a scan.
139
*
140
* Entries can either be initialized on the stack or on the heap.
141
*
142
* Initialization should be performed via a query object, using:
143
* - as_scan_select_init()
144
* - as_scan_select_inita()
145
*/
146
typedef
struct
as_scan_bins_s {
147
148
/**
149
* @private
150
* If true, then as_scan_destroy() will free this instance.
151
*/
152
bool
_free;
153
154
/**
155
* Number of entries allocated
156
*/
157
uint16_t capacity;
158
159
/**
160
* Number of entries used
161
*/
162
uint16_t size;
163
164
/**
165
* Sequence of entries
166
*/
167
as_bin_name
* entries;
168
169
}
as_scan_bins
;
170
171
/**
172
* In order to execute a scan using the Scan API, an as_scan object
173
* must be initialized and populated.
174
*
175
* ## Initialization
176
*
177
* Before using an as_scan, it must be initialized via either:
178
* - as_scan_init()
179
* - as_scan_new()
180
*
181
* as_scan_init() should be used on a stack allocated as_scan. It will
182
* initialize the as_scan with the given namespace and set. On success,
183
* it will return a pointer to the initialized as_scan. Otherwise, NULL
184
* is returned.
185
*
186
* ~~~~~~~~~~{.c}
187
* as_scan scan;
188
* as_scan_init(&scan, "namespace", "set");
189
* ~~~~~~~~~~
190
*
191
* as_scan_new() should be used to allocate and initialize a heap allocated
192
* as_scan. It will allocate the as_scan, then initialized it with the
193
* given namespace and set. On success, it will return a pointer to the
194
* initialized as_scan. Otherwise, NULL is returned.
195
*
196
* ~~~~~~~~~~{.c}
197
* as_scan * scan = as_scan_new("namespace", "set");
198
* ~~~~~~~~~~
199
*
200
* ## Destruction
201
*
202
* When you are finished with the as_scan, you can destroy it and associated
203
* resources:
204
*
205
* ~~~~~~~~~~{.c}
206
* as_scan_destroy(scan);
207
* ~~~~~~~~~~
208
*
209
* ## Usage
210
*
211
* An initialized as_query can be populated with additional fields.
212
*
213
* ### Selecting Bins
214
*
215
* as_scan_select() is used to specify the bins to be selected by the scan.
216
* If a scan specifies bins to be selected, then only those bins will be
217
* returned. If no bins are selected, then all bins will be returned.
218
*
219
* ~~~~~~~~~~{.c}
220
* as_scan_select(query, "bin1");
221
* as_scan_select(query, "bin2");
222
* ~~~~~~~~~~
223
*
224
* Before adding bins to select, the select structure must be initialized via
225
* either:
226
* - as_scan_select_inita() - Initializes the structure on the stack.
227
* - as_scan_select_init() - Initializes the structure on the heap.
228
*
229
* Both functions are given the number of bins to be selected.
230
*
231
* A complete example using as_scan_select_inita()
232
*
233
* ~~~~~~~~~~{.c}
234
* as_scan_select_inita(query, 2);
235
* as_scan_select(query, "bin1");
236
* as_scan_select(query, "bin2");
237
* ~~~~~~~~~~
238
*
239
* ### Returning only meta data
240
*
241
* A scan can return only record meta data, and exclude bins.
242
*
243
* ~~~~~~~~~~{.c}
244
* as_scan_set_nobins(scan, true);
245
* ~~~~~~~~~~
246
*
247
* ### Scan nodes in parallel
248
*
249
* A scan can be made to scan all the nodes in parallel
250
*
251
* ~~~~~~~~~~{.c}
252
* as_scan_set_concurrent(scan, true);
253
* ~~~~~~~~~~
254
*
255
* ### Scan a Percentage of Records
256
*
257
* A scan can define the percentage of record in the cluster to be scaned.
258
*
259
* ~~~~~~~~~~{.c}
260
* as_scan_set_percent(scan, 100);
261
* ~~~~~~~~~~
262
*
263
* ### Scan a Priority
264
*
265
* To set the priority of the scan, the set as_scan.priority.
266
*
267
* The priority of a scan can be defined as either:
268
* - `AS_SCAN_PRIORITY_AUTO`
269
* - `AS_SCAN_PRIORITY_LOW`
270
* - `AS_SCAN_PRIORITY_MEDIUM`
271
* - `AS_SCAN_PRIORITY_HIGH`
272
*
273
* ~~~~~~~~~~{.c}
274
* as_scan_set_priority(scan, AS_SCAN_PRIORITY_LOW);
275
* ~~~~~~~~~~
276
*
277
* ### Applying a UDF to each Record Scanned
278
*
279
* A UDF can be applied to each record scanned.
280
*
281
* To define the UDF for the scan, use as_scan_apply_each().
282
*
283
* ~~~~~~~~~~{.c}
284
* as_scan_apply_each(scan, "udf_module", "udf_function", arglist);
285
* ~~~~~~~~~~
286
*
287
* @ingroup client_objects
288
*/
289
typedef
struct
as_scan_s {
290
291
/**
292
* @private
293
* If true, then as_scan_destroy() will free this instance.
294
*/
295
bool
_free;
296
297
/**
298
* Priority of scan.
299
*
300
* Default value is AS_SCAN_PRIORITY_DEFAULT.
301
*/
302
as_scan_priority
priority;
303
304
/**
305
* Percentage of the data to scan.
306
*
307
* Default value is AS_SCAN_PERCENT_DEFAULT.
308
*/
309
uint8_t percent;
310
311
/**
312
* Set to true if the scan should return only the metadata of the record.
313
*
314
* Default value is AS_SCAN_NOBINS_DEFAULT.
315
*/
316
bool
no_bins;
317
318
/**
319
* Set to true if the scan should scan all the nodes in parallel
320
*
321
* Default value is AS_SCAN_CONCURRENT_DEFAULT.
322
*/
323
bool
concurrent;
324
325
/**
326
* @memberof as_scan
327
* Namespace to be scanned.
328
*
329
* Should be initialized via either:
330
* - as_scan_init() - To initialize a stack allocated scan.
331
* - as_scan_new() - To heap allocate and initialize a scan.
332
*
333
*/
334
as_namespace
ns
;
335
336
/**
337
* Set to be scanned.
338
*
339
* Should be initialized via either:
340
* - as_scan_init() - To initialize a stack allocated scan.
341
* - as_scan_new() - To heap allocate and initialize a scan.
342
*
343
*/
344
as_set
set;
345
346
/**
347
* Name of bins to select.
348
*
349
* Use either of the following function to initialize:
350
* - as_scan_select_init() - To initialize on the heap.
351
* - as_scan_select_inita() - To initialize on the stack.
352
*
353
* Use as_scan_select() to populate.
354
*/
355
as_scan_bins
select;
356
357
/**
358
* Apply the UDF for each record scanned on the server.
359
*
360
* Should be set via `as_scan_apply_each()`.
361
*/
362
as_udf_call
apply_each;
363
364
}
as_scan
;
365
366
/******************************************************************************
367
* INSTANCE FUNCTIONS
368
*****************************************************************************/
369
370
/**
371
* Initializes a scan.
372
*
373
* ~~~~~~~~~~{.c}
374
* as_scan scan;
375
* as_scan_init(&scan, "test", "demo");
376
* ~~~~~~~~~~
377
*
378
* When you no longer require the scan, you should release the scan and
379
* related resources via `as_scan_destroy()`.
380
*
381
* @param scan The scan to initialize.
382
* @param ns The namespace to scan.
383
* @param set The set to scan.
384
*
385
* @returns On succes, the initialized scan. Otherwise NULL.
386
*
387
* @relates as_scan
388
* @ingroup as_scan_object
389
*/
390
as_scan
*
as_scan_init
(
as_scan
* scan,
const
as_namespace
ns
,
const
as_set
set);
391
392
/**
393
* Create and initializes a new scan on the heap.
394
*
395
* ~~~~~~~~~~{.c}
396
* as_scan * scan = as_scan_new("test","demo");
397
* ~~~~~~~~~~
398
*
399
* When you no longer require the scan, you should release the scan and
400
* related resources via `as_scan_destroy()`.
401
*
402
* @param ns The namespace to scan.
403
* @param set The set to scan.
404
*
405
* @returns On success, a new scan. Otherwise NULL.
406
*
407
* @relates as_scan
408
* @ingroup as_scan_object
409
*/
410
as_scan
*
as_scan_new
(
const
as_namespace
ns
,
const
as_set
set);
411
412
/**
413
* Releases all resources allocated to the scan.
414
*
415
* ~~~~~~~~~~{.c}
416
* as_scan_destroy(scan);
417
* ~~~~~~~~~~
418
*
419
* @relates as_scan
420
* @ingroup as_scan_object
421
*/
422
void
as_scan_destroy
(
as_scan
* scan);
423
424
/******************************************************************************
425
* SELECT FUNCTIONS
426
*****************************************************************************/
427
428
/**
429
* Initializes `as_scan.select` with a capacity of `n` using `alloca`
430
*
431
* For heap allocation, use `as_scan_select_init()`.
432
*
433
* ~~~~~~~~~~{.c}
434
* as_scan_select_inita(&scan, 2);
435
* as_scan_select(&scan, "bin1");
436
* as_scan_select(&scan, "bin2");
437
* ~~~~~~~~~~
438
*
439
* @param __scan The scan to initialize.
440
* @param __n The number of bins to allocate.
441
*
442
* @ingroup as_scan_object
443
*/
444
#define as_scan_select_inita(__scan, __n) \
445
if ( (__scan) != NULL && (__scan)->select.entries == NULL ) {\
446
(__scan)->select.entries = (as_bin_name *) alloca(__n * sizeof(as_bin_name));\
447
if ( (__scan)->select.entries ) { \
448
(__scan)->select._free = false;\
449
(__scan)->select.capacity = __n;\
450
(__scan)->select.size = 0;\
451
}\
452
}
453
454
/**
455
* Initializes `as_scan.select` with a capacity of `n` using `malloc()`.
456
*
457
* For stack allocation, use `as_scan_select_inita()`.
458
*
459
* ~~~~~~~~~~{.c}
460
* as_scan_select_init(&scan, 2);
461
* as_scan_select(&scan, "bin1");
462
* as_scan_select(&scan, "bin2");
463
* ~~~~~~~~~~
464
*
465
* @param scan The scan to initialize.
466
* @param n The number of bins to allocate.
467
*
468
* @return On success, the initialized. Otherwise an error occurred.
469
*
470
* @relates as_scan
471
* @ingroup as_scan_object
472
*/
473
bool
as_scan_select_init
(
as_scan
* scan, uint16_t n);
474
475
/**
476
* Select bins to be projected from matching records.
477
*
478
* You have to ensure as_scan.select has sufficient capacity, prior to
479
* adding a bin. If capacity is insufficient then false is returned.
480
*
481
* ~~~~~~~~~~{.c}
482
* as_scan_select_init(&scan, 2);
483
* as_scan_select(&scan, "bin1");
484
* as_scan_select(&scan, "bin2");
485
* ~~~~~~~~~~
486
*
487
* @param scan The scan to modify.
488
* @param bin The name of the bin to select.
489
*
490
* @return On success, true. Otherwise an error occurred.
491
*
492
* @relates as_scan
493
* @ingroup as_scan_object
494
*/
495
bool
as_scan_select
(
as_scan
* scan,
const
char
* bin);
496
497
/******************************************************************************
498
* MODIFIER FUNCTIONS
499
*****************************************************************************/
500
501
/**
502
* The percentage of data to scan.
503
*
504
* ~~~~~~~~~~{.c}
505
* as_scan_set_percent(&q, 100);
506
* ~~~~~~~~~~
507
*
508
* @param scan The scan to set the priority on.
509
* @param percent The percent to scan.
510
*
511
* @return On success, true. Otherwise an error occurred.
512
*
513
* @relates as_scan
514
* @ingroup as_scan_object
515
*/
516
bool
as_scan_set_percent
(
as_scan
* scan, uint8_t percent);
517
518
/**
519
* Set the priority for the scan.
520
*
521
* ~~~~~~~~~~{.c}
522
* as_scan_set_priority(&q, AS_SCAN_PRIORITY_LOW);
523
* ~~~~~~~~~~
524
*
525
* @param scan The scan to set the priority on.
526
* @param priority The priority for the scan.
527
*
528
* @return On success, true. Otherwise an error occurred.
529
*
530
* @relates as_scan
531
* @ingroup as_scan_object
532
*/
533
bool
as_scan_set_priority
(
as_scan
* scan,
as_scan_priority
priority);
534
535
/**
536
* Do not return bins. This will only return the metadata for the records.
537
*
538
* ~~~~~~~~~~{.c}
539
* as_scan_set_nobins(&q, true);
540
* ~~~~~~~~~~
541
*
542
* @param scan The scan to set the priority on.
543
* @param nobins If true, then do not return bins.
544
*
545
* @return On success, true. Otherwise an error occurred.
546
*
547
* @relates as_scan
548
* @ingroup as_scan_object
549
*/
550
bool
as_scan_set_nobins
(
as_scan
* scan,
bool
nobins);
551
552
/**
553
* Scan all the nodes in prallel
554
*
555
* ~~~~~~~~~~{.c}
556
* as_scan_set_concurrent(&q, true);
557
* ~~~~~~~~~~
558
*
559
* @param scan The scan to set the concurrency on.
560
* @param concurrent If true, scan all the nodes in parallel
561
*
562
* @return On success, true. Otherwise an error occurred.
563
*/
564
bool
as_scan_set_concurrent
(
as_scan
* scan,
bool
concurrent);
565
566
/**
567
* Apply a UDF to each record scanned on the server.
568
*
569
* ~~~~~~~~~~{.c}
570
* as_arraylist arglist;
571
* as_arraylist_init(&arglist, 2, 0);
572
* as_arraylist_append_int64(&arglist, 1);
573
* as_arraylist_append_int64(&arglist, 2);
574
*
575
* as_scan_apply_each(&q, "module", "func", (as_list *) &arglist);
576
*
577
* as_arraylist_destroy(&arglist);
578
* ~~~~~~~~~~
579
*
580
* @param scan The scan to apply the UDF to.
581
* @param module The module containing the function to execute.
582
* @param function The function to execute.
583
* @param arglist The arguments for the function.
584
*
585
* @return On success, true. Otherwise an error occurred.
586
*
587
* @relates as_scan
588
* @ingroup as_scan_object
589
*/
590
bool
as_scan_apply_each
(
as_scan
* scan,
const
char
* module,
const
char
*
function
,
as_list
* arglist);