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-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>
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  */
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  */
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 
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 
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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 
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:26
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:51
char as_udf_function_name[AS_UDF_FUNCTION_MAX_SIZE]
Definition: as_udf.h:78
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:48
Definition: as_key.h:193
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)