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