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