Main Page
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Friends
Macros
Groups
Pages
aerospike
aerospike_lset.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
* Functionality related to Large Set Data Type
21
*/
22
23
#include <
aerospike/aerospike.h
>
24
#include <
aerospike/as_error.h
>
25
#include <
aerospike/as_ldt.h
>
26
#include <
aerospike/as_list.h
>
27
#include <
aerospike/as_operations.h
>
28
#include <
aerospike/as_policy.h
>
29
#include <
aerospike/as_status.h
>
30
#include <
aerospike/as_key.h
>
31
#include <
aerospike/as_val.h
>
32
#include <
aerospike/as_boolean.h
>
33
34
/******************************************************************************
35
* FUNCTIONS
36
*****************************************************************************/
37
38
/**
39
* Add a value into the lset.
40
*
41
* ~~~~~~~~~~{.c}
42
* as_key key;
43
* as_key_init(&key, "myns", "myset", "mykey");
44
*
45
* as_ldt lset;
46
* as_ldt_init(&lset, "mylset", AS_LDT_LSET, NULL);
47
*
48
* as_integer ival;
49
* as_integer_init(&ival, 123);
50
*
51
* if ( aerospike_lset_add(&as, &err, NULL, &key, &lset, (as_val *) &ival) != AEROSPIKE_OK ) {
52
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
53
* }
54
* ~~~~~~~~~~
55
*
56
* @param as The aerospike instance to use for this operation.
57
* @param err The as_error to be populated if an error occurs.
58
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
59
* @param key The key of the record.
60
* @param ldt The ldt bin to insert values to.
61
* @param val The value to insert into the lset.
62
*
63
* @return AEROSPIKE_OK if successful. Otherwise an error.
64
*
65
* @ingroup ldt_operations
66
*/
67
as_status
aerospike_lset_add
(
68
aerospike
* as,
as_error
* err,
const
as_policy_apply
* policy,
69
const
as_key
* key,
const
as_ldt
* ldt,
const
as_val
* val);
70
71
/**
72
* Add a list of values into the lset.
73
*
74
* ~~~~~~~~~~{.c}
75
* as_key key;
76
* as_key_init(&key, "myns", "myset", "mykey");
77
*
78
* as_ldt lset;
79
* as_ldt_init(&lset, "mylset", AS_LDT_LSET, NULL);
80
*
81
*
82
* as_arraylist vals;
83
* as_arraylist_inita(&vals, 2);
84
* as_string s;
85
* as_string_init(s,"a string",false);
86
* as_arraylist_append_string(&vals, s);
87
* as_arraylist_append_int64(&vals, 35);
88
*
89
* if ( aerospike_lset_add_all(&as, &err, NULL, &key, &lset, (as_list *)vals) != AEROSPIKE_OK ) {
90
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
91
* }
92
*
93
* ~~~~~~~~~~
94
*
95
* @param as The aerospike instance to use for this operation.
96
* @param err The as_error to be populated if an error occurs.
97
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
98
* @param key The key of the record.
99
* @param ldt The ldt bin to insert values to.
100
* @param vals The list of values to insert into the lset.
101
*
102
* @return AEROSPIKE_OK if successful. Otherwise an error.
103
*
104
* @ingroup ldt_operations
105
*/
106
as_status
aerospike_lset_add_all
(
107
aerospike
* as,
as_error
* err,
const
as_policy_apply
* policy,
108
const
as_key
* key,
const
as_ldt
* ldt,
const
as_list
* vals);
109
110
/**
111
* See if a value exists in an lset
112
*
113
* ~~~~~~~~~~{.c}
114
* as_key key;
115
* as_key_init(&key, "myns", "myset", "mykey");
116
*
117
* as_ldt lset;
118
* as_ldt_init(&lset, "mylset", AS_LDT_LSET, NULL);
119
*
120
* as_integer ival;
121
* as_integer_init(&ival, 123);
122
*
123
* boolean exists = false;
124
*
125
* if ( aerospike_lset_exists(&as, &err, NULL, &key, &lset, &ival, &exists) != AEROSPIKE_OK ) {
126
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
127
* }
128
* else {
129
* // do logic because element exists
130
* }
131
* ~~~~~~~~~~
132
*
133
* @param as The aerospike instance to use for this operation.
134
* @param err The as_error to be populated if an error occurs.
135
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
136
* @param key The key of the record.
137
* @param ldt The lset bin to lookup from. If not an lset bin, will return error.
138
* @param val The value we're searching for.
139
* @param exists Returned boolean value to indicate value exists.
140
*
141
* @return AEROSPIKE_OK if successful. Otherwise an error.
142
*
143
* @ingroup ldt_operations
144
*/
145
146
as_status
aerospike_lset_exists
(
147
aerospike
* as,
as_error
* err,
const
as_policy_apply
* policy,
148
const
as_key
* key,
const
as_ldt
* ldt,
const
as_val
* val,
149
as_boolean
*exists);
150
151
152
/**
153
* Fetch (get) a value from the lset.
154
* Note that this is useful mainly in the case where the search criteria for
155
* an object is less than the entire object -- and that is when the standard
156
* defaults are overridden and the unique_identifier() function is employed
157
* to use only part of the object for search and compare.
158
* The unique_identifier() function is defined on create -- and declared in
159
* the USER_MODULE.
160
*
161
* ~~~~~~~~~~{.c}
162
* as_key key;
163
* as_key_init(&key, "myns", "myset", "mykey");
164
*
165
* as_ldt lset;
166
* as_ldt_init(&lset, "mylset", AS_LDT_LSET, NULL);
167
*
168
* as_integer ival;
169
* as_integer_init(&ival, 123);
170
*
171
* as_val * p_return_val;
172
*
173
* if ( aerospike_lset_exists(&as, &err, NULL, &key, &lset, &ival, &p_return_value) != AEROSPIKE_OK ) {
174
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
175
* }
176
* else {
177
* // do logic because element exists
178
* }
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 key The key of the record.
185
* @param ldt The lset bin to lookup from. If not an lset bin, will return error.
186
* @param val The value we're searching for.
187
* @param pp_return_val Returned value.
188
*
189
* @return AEROSPIKE_OK if successful. Otherwise an error.
190
*
191
* @ingroup ldt_operations
192
*/
193
194
as_status
aerospike_lset_get
(
195
aerospike
* as,
as_error
* err,
const
as_policy_apply
* policy,
196
const
as_key
* key,
const
as_ldt
* ldt,
const
as_val
* val,
197
as_val
** pp_return_val );
198
199
/**
200
* Given an lset bin, filter the set of objects using the given filter function.
201
* If no filter function is specified, all values in the set will be returned.
202
*
203
* ~~~~~~~~~~{.c}
204
* as_key key;
205
* as_key_init(&key, "myns", "myset", "mykey");
206
*
207
* as_ldt lset;
208
* as_ldt_init(&lset, "mylset", AS_LDT_LSET, NULL);
209
*
210
* as_list *list = NULL;
211
*
212
* if ( aerospike_lset_filter(&as, &err, NULL, &key, &lset,
213
* "search_filter", NULL, (as_list *) &list) != AEROSPIKE_OK ) {
214
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
215
* }
216
* else {
217
* // process the returned elements
218
* as_arraylist_destroy(list);
219
* }
220
* ~~~~~~~~~~
221
*
222
* @param as The aerospike instance to use for this operation.
223
* @param err The as_error to be populated if an error occurs.
224
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
225
* @param key The key of the record.
226
* @param ldt The lset bin to search from. If not an lset bin, will return error.
227
* @param filter The name of the User-Defined-Function to use as a search filter.
228
* @param fargs The list of parameters passed in to the User-Defined-Function filter.
229
* @param list The pointer to a list of elements returned from search function. Pointer should
230
* be NULL passed in.
231
*
232
* @return AEROSPIKE_OK if successful. Otherwise an error.
233
*
234
* @ingroup ldt_operations
235
*/
236
as_status
aerospike_lset_filter
(
237
aerospike
* as,
as_error
* err,
const
as_policy_apply
* policy,
238
const
as_key
* key,
const
as_ldt
* ldt,
239
const
as_udf_function_name
filter,
const
as_list
*filter_args,
240
as_list
** elements );
241
242
/**
243
* Given an lset bin, scan for all the values in the set
244
*
245
* ~~~~~~~~~~{.c}
246
* as_key key;
247
* as_key_init(&key, "myns", "myset", "mykey");
248
*
249
* as_ldt lset;
250
* as_ldt_init(&lset, "mylset", AS_LDT_LSET, NULL);
251
*
252
* as_list *list = NULL;
253
*
254
* if ( aerospike_lset_scan(&as, &err, NULL, &key, &lset,
255
* "search_filter", NULL, (as_list *) &list) != AEROSPIKE_OK ) {
256
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
257
* }
258
* else {
259
* // process the returned elements
260
* as_arraylist_destroy(list);
261
* }
262
* ~~~~~~~~~~
263
*
264
* @param as The aerospike instance to use for this operation.
265
* @param err The as_error to be populated if an error occurs.
266
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
267
* @param key The key of the record.
268
* @param ldt The lset bin to search from. If not an lset bin, will return error.
269
* @param list The pointer to a list of elements returned from search function. Pointer should
270
* be NULL passed in.
271
*
272
* @return AEROSPIKE_OK if successful. Otherwise an error.
273
*
274
* @ingroup ldt_operations
275
*/
276
as_status
aerospike_lset_scan
(
277
aerospike
* as,
as_error
* err,
const
as_policy_apply
* policy,
278
const
as_key
* key,
const
as_ldt
* ldt,
279
as_list
** elements );
280
281
/**
282
* Look up a lset and find how many elements it contains
283
*
284
* ~~~~~~~~~~{.c}
285
* as_key key;
286
* as_key_init(&key, "myns", "myset", "mykey");
287
*
288
* as_ldt lset;
289
* as_ldt_init(&lset, "mylset", AS_LDT_LSET, NULL);
290
* uint32_t lset_size = 0;
291
*
292
* if ( aerospike_lset_size(&as, &err, NULL, &key, &lset, &lset_size) != AEROSPIKE_OK ) {
293
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
294
* }
295
* ~~~~~~~~~~
296
*
297
* @param as The aerospike instance to use for this operation.
298
* @param err The as_error to be populated if an error occurs.
299
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
300
* @param key The key of the record.
301
* @param ldt The lset to operate on. If not an lset bin, will return error.
302
* @param n Return the number of elements in the lset.
303
*
304
* @return AEROSPIKE_OK if successful. Otherwise an error.
305
*
306
* @ingroup ldt_operations
307
*/
308
as_status
aerospike_lset_size
(
309
aerospike
* as,
as_error
* err,
const
as_policy_apply
* policy,
310
const
as_key
* key,
const
as_ldt
* ldt,
311
uint32_t *n
312
);
313
314
/**
315
* Delete the given value from the lset
316
*
317
* ~~~~~~~~~~{.c}
318
* as_key key;
319
* as_key_init(&key, "myns", "myset", "mykey");
320
*
321
* as_ldt lset;
322
* as_ldt_init(&lset, "lset", AS_LDT_LSET, NULL);
323
*
324
* as_integer ival;
325
* as_integer_init(&ival, 123);
326
*
327
* if ( aerospike_lset_remove(&as, &err, NULL, &key, &lset, &ival) != AEROSPIKE_OK ) {
328
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
329
* }
330
* ~~~~~~~~~~
331
*
332
* @param as The aerospike instance to use for this operation.
333
* @param err The as_error to be populated if an error occurs.
334
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
335
* @param key The key of the record.
336
* @param ldt The lset bin to delete from. If not an lset bin, will return error.
337
* @param val The value to delete from the set.
338
*
339
* @return AEROSPIKE_OK if successful. Otherwise an error.
340
*
341
* @ingroup ldt_operations
342
*/
343
as_status
aerospike_lset_remove
(
344
aerospike
* as,
as_error
* err,
const
as_policy_apply
* policy,
345
const
as_key
* key,
const
as_ldt
* ldt,
const
as_val
*element
346
);
347
348
/**
349
* Destroy the lset bin
350
*
351
* ~~~~~~~~~~{.c}
352
* as_key key;
353
* as_key_init(&key, "myns", "myset", "mykey");
354
*
355
* as_ldt lset;
356
* as_ldt_init(&lset, "mylset", AS_LDT_LSET, NULL);
357
*
358
* if ( aerospike_lset_destroy(&as, &err, NULL, &key, &lset) != AEROSPIKE_OK ) {
359
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
360
* }
361
* ~~~~~~~~~~
362
*
363
* @param as The aerospike instance to use for this operation.
364
* @param err The as_error to be populated if an error occurs.
365
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
366
* @param key The key of the record.
367
* @param ldt The lset bin to destroy. If not an lset bin, will return error.
368
*
369
* @return AEROSPIKE_OK if successful. Otherwise an error.
370
*
371
* @ingroup ldt_operations
372
*/
373
as_status
aerospike_lset_destroy
(
374
aerospike
* as,
as_error
* err,
const
as_policy_apply
* policy,
375
const
as_key
* key,
const
as_ldt
* ldt
376
);
377
378
/**
379
* Change an LDT storage capacity (in number of elements)
380
*
381
* ~~~~~~~~~~{.c}
382
* as_key key;
383
* as_key_init(&key, "myns", "myset", "mykey");
384
*
385
* as_ldt lset;
386
* as_ldt_init(&lset, "mylset", AS_LDT_LMAP, NULL);
387
* uint32_t ldt_capacity = 0;
388
*
389
* if ( aerospike_lset_set_capacity(&as, &err, NULL, &key, &lset, ldt_capacity) != AEROSPIKE_OK ) {
390
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
391
* }
392
* ~~~~~~~~~~
393
*
394
* @param as The aerospike instance to use for this operation.
395
* @param err The as_error to be populated if an error occurs.
396
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
397
* @param key The key of the record.
398
* @param ldt The LDT to check
399
* @param ldt_capacity The number of elements cap for the LDT.
400
*
401
* @return AEROSPIKE_OK if successful. Otherwise an error.
402
*
403
* @ingroup ldt_operations
404
*/
405
as_status
aerospike_lset_set_capacity
(
406
aerospike
* as,
as_error
* err,
const
as_policy_apply
* policy,
407
const
as_key
* key,
const
as_ldt
* ldt, uint32_t ldt_capacity
408
);
409
410
/**
411
* Get an LDTs storage capacity (in number of elements)
412
*
413
* ~~~~~~~~~~{.c}
414
* as_key key;
415
* as_key_init(&key, "myns", "myset", "mykey");
416
*
417
* as_ldt lset;
418
* as_ldt_init(&lset, "mylset", AS_LDT_LMAP, NULL);
419
* uint32_t ldt_capacity = 0;
420
*
421
* if ( aerospike_lset_get_capacity(&as, &err, NULL, &key, &lset, &ldt_capacity) != AEROSPIKE_OK ) {
422
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
423
* }
424
* ~~~~~~~~~~
425
*
426
* @param as The aerospike instance to use for this operation.
427
* @param err The as_error to be populated if an error occurs.
428
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
429
* @param key The key of the record.
430
* @param ldt The LDT bin to operate on
431
* @param ldt_capacity The LDT Capacity, in terms of elements, not bytes.
432
*
433
* @return AEROSPIKE_OK if successful. Otherwise an error.
434
*
435
* @ingroup ldt_operations
436
*/
437
as_status
aerospike_lset_get_capacity
(
438
aerospike
* as,
as_error
* err,
const
as_policy_apply
* policy,
439
const
as_key
* key,
const
as_ldt
* ldt,
440
uint32_t *ldt_capacity
441
);
442
443
/**
444
* Check to see if an LDT object exists in this record bin.
445
*
446
* ~~~~~~~~~~{.c}
447
* as_key key;
448
* as_key_init(&key, "myns", "myset", "mykey");
449
*
450
* as_ldt lset;
451
* as_ldt_init(&lset, "mylset", AS_LDT_LSET, NULL);
452
* uint32_t ldt_exists = 0;
453
*
454
* if ( aerospike_lset_ldt_exists(&as, &err, NULL, &key, &lset, &ldt_exists) != AEROSPIKE_OK ) {
455
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
456
* }
457
* ~~~~~~~~~~
458
*
459
* @param as The aerospike instance to use for this operation.
460
* @param err The as_error to be populated if an error occurs.
461
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
462
* @param key The key of the record.
463
* @param ldt The LDT to operate on. If not an LMAP bin, will return error.
464
* @param ldt_exists Ptr to as_boolean: Set to TRUE if ldt exists, otherwise false.
465
*
466
* @return AEROSPIKE_OK if successful. Otherwise an error.
467
*
468
* @ingroup ldt_operations
469
*/
470
as_status
aerospike_lset_ldt_exists
(
471
aerospike
* as,
as_error
* err,
const
as_policy_apply
* policy,
472
const
as_key
* key,
const
as_ldt
* ldt,
473
as_boolean
*ldt_exists
474
);
475