All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
aerospike_lmap.h
Go to the documentation of this file.
1 /*
2  * Copyright 2008-2015 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 #ifdef __cplusplus
20 extern "C" {
21 #endif
22 
23 /**
24  * Functionality related to Large Map Data Type
25  */
26 
27 #include <aerospike/aerospike.h>
28 #include <aerospike/as_error.h>
29 #include <aerospike/as_ldt.h>
30 #include <aerospike/as_list.h>
32 #include <aerospike/as_policy.h>
33 #include <aerospike/as_status.h>
34 #include <aerospike/as_key.h>
35 #include <aerospike/as_val.h>
36 #include <aerospike/as_boolean.h>
37 
38 /******************************************************************************
39  * FUNCTIONS
40  *****************************************************************************/
41 
42 /**
43  * Add a value into the lmap.
44  *
45  * ~~~~~~~~~~{.c}
46  * as_key key;
47  * as_key_init(&key, "myns", "myset", "mykey");
48  *
49  * as_ldt lmap;
50  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
51  *
52  * as_integer ival;
53  * as_integer_init(&ival, 123);
54  *
55  * if ( aerospike_lmap_put(&as, &err, NULL, &key, &lmap, (const as_val *) &ival, (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 mkey The map-key.
66  * @param val The map-value associated with mkey.
67  *
68  * @return AEROSPIKE_OK if successful. Otherwise an error.
69  *
70  * @ingroup ldt_operations
71  */
73  aerospike * as, as_error * err, const as_policy_apply * policy,
74  const as_key * key, const as_ldt * ldt,
75  const as_val * mkey, const as_val * mval
76  );
77 
78 /**
79  * Add multiple entries into the lmap.
80  *
81  * ~~~~~~~~~~{.c}
82  * as_key key;
83  * as_key_init(&key, "myns", "myset", "mykey");
84  *
85  * as_ldt lmap;
86  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
87  *
88  *
89  * as_arraylist vals;
90  * as_arraylist_inita(&vals, 2);
91  * as_string s;
92  * as_string_init(s,"a string",false);
93  * as_arraylist_append_string(&vals, s);
94  * as_arraylist_append_int64(&vals, 35);
95  *
96  * if ( aerospike_lmap_put_all(&as, &err, NULL, &key, &lmap, (const as_map *)vals) != AEROSPIKE_OK ) {
97  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
98  * }
99  *
100  * ~~~~~~~~~~
101  *
102  * @param as The aerospike instance to use for this operation.
103  * @param err The as_error to be populated if an error occurs.
104  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
105  * @param key The key of the record.
106  * @param ldt The ldt bin to insert values to.
107  * @param vals A map containing the entries to add to the lmap.
108  *
109  * @return AEROSPIKE_OK if successful. Otherwise an error.
110  *
111  * @ingroup ldt_operations
112  */
114  aerospike * as, as_error * err, const as_policy_apply * policy,
115  const as_key * key, const as_ldt * ldt, const as_map * vals
116  );
117 
118 /**
119  * Get the value of an entry in the Lmap, using the given map-key
120  *
121  * ~~~~~~~~~~{.c}
122  * as_key key;
123  * as_key_init(&key, "myns", "myset", "mykey");
124  *
125  * as_ldt lmap;
126  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
127  *
128  * as_integer ival;
129  * as_integer_init(&ival, 123);
130  *
131  * boolean exists = false;
132  *
133  * if ( aerospike_lmap_get(&as, &err, NULL, &key, &lmap, &ikey, &p_val) != 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  * @param as The aerospike instance to use for this operation.
142  * @param err The as_error to be populated if an error occurs.
143  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
144  * @param key The key of the record.
145  * @param ldt The lmap bin to lookup from. If not an lmap bin, will return error.
146  * @param exists Returned boolean value to indicate value exists.
147  *
148  * @return AEROSPIKE_OK if successful. Otherwise an error.
149  *
150  * @ingroup ldt_operations
151  */
152 
154  aerospike * as, as_error * err, const as_policy_apply * policy,
155  const as_key * key, const as_ldt * ldt, const as_val * mkey,
156  as_val ** mval
157  );
158 
159 /**
160  * Get all the entries in an lmap
161  *
162  * ~~~~~~~~~~{.c}
163  * as_key key;
164  * as_key_init(&key, "myns", "myset", "mykey");
165  *
166  * as_ldt lmap;
167  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
168  *
169  * as_map *p_map = NULL;
170  *
171  * if ( aerospike_lmap_get_all(&as, &err, NULL, &key, &lmap, &p_map) != AEROSPIKE_OK ) {
172  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
173  * }
174  * else {
175  * // do logic because element exists
176  * }
177  * ~~~~~~~~~~
178  *
179  * @param as The aerospike instance to use for this operation.
180  * @param err The as_error to be populated if an error occurs.
181  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
182  * @param key The key of the record.
183  * @param ldt The lmap bin to lookup from. If not an lmap bin, will return error.
184  * @param elements Returned pointer to the map of entries.
185  *
186  * @return AEROSPIKE_OK if successful. Otherwise an error.
187  *
188  * @ingroup ldt_operations
189  */
190 
192  aerospike * as, as_error * err, const as_policy_apply * policy,
193  const as_key * key, const as_ldt * ldt,
194  as_map ** elements
195  );
196 
197 /**
198  * Given an lmap bin, scan through all entries in the map, and apply the
199  * given filter function. If no filter function is specified, all values
200  * in the lmap will be returned.
201  *
202  * ~~~~~~~~~~{.c}
203  * as_key key;
204  * as_key_init(&key, "myns", "myset", "mykey");
205  *
206  * as_ldt lmap;
207  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
208  *
209  * as_map *p_map = NULL;
210  *
211  * if ( aerospike_lmap_filter(&as, &err, NULL, &key, &lmap,
212  * "counter_filter", NULL, (as_map *) &p_map) != AEROSPIKE_OK ) {
213  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
214  * }
215  * else {
216  * // process the returned elements
217  * as_map_destroy(p_map);
218  * }
219  * ~~~~~~~~~~
220  *
221  * @param as The aerospike instance to use for this operation.
222  * @param err The as_error to be populated if an error occurs.
223  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
224  * @param key The key of the record.
225  * @param ldt The lmap bin to operate on. If not an lmap bin, will return error.
226  * @param filter The name of the User-Defined-Function to use as a read-filter.
227  * The UDF should either return the entry, or nil, if filtered out.
228  * @param fargs The list of parameters passed in to the User-Defined-Function filter.
229  * @param elements The pointer to a map of entries returned from the 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_map ** elements
241  );
242 
243 /**
244  * Look up a lmap and find how many elements it contains
245  *
246  * ~~~~~~~~~~{.c}
247  * as_key key;
248  * as_key_init(&key, "myns", "myset", "mykey");
249  *
250  * as_ldt lmap;
251  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
252  * uint32_t lmap_size = 0;
253  *
254  * if ( aerospike_lmap_size(&as, &err, NULL, &key, &lmap, &lmap_size) != AEROSPIKE_OK ) {
255  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
256  * }
257  * ~~~~~~~~~~
258  *
259  * @param as The aerospike instance to use for this operation.
260  * @param err The as_error to be populated if an error occurs.
261  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
262  * @param key The key of the record.
263  * @param ldt The lmap to operate on. If not an lmap bin, will return error.
264  * @param n Return the number of elements in the lmap.
265  *
266  * @return AEROSPIKE_OK if successful. Otherwise an error.
267  *
268  * @ingroup ldt_operations
269  */
271  aerospike * as, as_error * err, const as_policy_apply * policy,
272  const as_key * key, const as_ldt * ldt,
273  uint32_t *n
274  );
275 
276 /**
277  * Delete the given value from the lmap
278  *
279  * ~~~~~~~~~~{.c}
280  * as_key key;
281  * as_key_init(&key, "myns", "myset", "mykey");
282  *
283  * as_ldt lmap;
284  * as_ldt_init(&lmap, "lmap", AS_LDT_LMAP, NULL);
285  *
286  * as_integer ival;
287  * as_integer_init(&ival, 123);
288  *
289  * if ( aerospike_lmap_remove(&as, &err, NULL, &key, &lmap, (const as_val*)&ikey) != AEROSPIKE_OK ) {
290  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
291  * }
292  * ~~~~~~~~~~
293  *
294  * @param as The aerospike instance to use for this operation.
295  * @param err The as_error to be populated if an error occurs.
296  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
297  * @param key The key of the record.
298  * @param ldt The lmap bin to delete from. If not an lmap bin, will return error.
299  * @param val The value to delete from the set.
300  *
301  * @return AEROSPIKE_OK if successful. Otherwise an error.
302  *
303  * @ingroup ldt_operations
304  */
306  aerospike * as, as_error * err, const as_policy_apply * policy,
307  const as_key * key, const as_ldt * ldt, const as_val *mkey
308  );
309 
310 /**
311  * Destroy the lmap bin
312  *
313  * ~~~~~~~~~~{.c}
314  * as_key key;
315  * as_key_init(&key, "myns", "myset", "mykey");
316  *
317  * as_ldt lmap;
318  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
319  *
320  * if ( aerospike_lmap_destroy(&as, &err, NULL, &key, &lmap) != AEROSPIKE_OK ) {
321  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
322  * }
323  * ~~~~~~~~~~
324  *
325  * @param as The aerospike instance to use for this operation.
326  * @param err The as_error to be populated if an error occurs.
327  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
328  * @param key The key of the record.
329  * @param ldt The lmap bin to destroy. If not an lmap bin, will return error.
330  *
331  * @return AEROSPIKE_OK if successful. Otherwise an error.
332  *
333  * @ingroup ldt_operations
334  */
336  aerospike * as, as_error * err, const as_policy_apply * policy,
337  const as_key * key, const as_ldt * ldt
338  );
339 
340 /**
341  * Change an LDT storage capacity (in number of elements)
342  *
343  * ~~~~~~~~~~{.c}
344  * as_key key;
345  * as_key_init(&key, "myns", "myset", "mykey");
346  *
347  * as_ldt lmap;
348  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
349  * uint32_t ldt_capacity = 0;
350  *
351  * if ( aerospike_lmap_set_capacity(&as, &err, NULL, &key, &lmap, ldt_capacity) != AEROSPIKE_OK ) {
352  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
353  * }
354  * ~~~~~~~~~~
355  *
356  * @param as The aerospike instance to use for this operation.
357  * @param err The as_error to be populated if an error occurs.
358  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
359  * @param key The key of the record.
360  * @param ldt The LDT to check
361  * @param ldt_capacity The new capacity for this LDT, in terms of elements, not bytes
362  *
363  * @return AEROSPIKE_OK if successful. Otherwise an error.
364  *
365  * @ingroup ldt_operations
366  */
368  aerospike * as, as_error * err, const as_policy_apply * policy,
369  const as_key * key, const as_ldt * ldt, uint32_t ldt_capacity
370  );
371 
372 /**
373  * Get an LDTs storage capacity (in number of elements)
374  *
375  * ~~~~~~~~~~{.c}
376  * as_key key;
377  * as_key_init(&key, "myns", "myset", "mykey");
378  *
379  * as_ldt lmap;
380  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
381  * uint32_t ldt_capacity = 0;
382  *
383  * if ( aerospike_lmap_get_capacity(&as, &err, NULL, &key, &lmap, &ldt_capacity) != AEROSPIKE_OK ) {
384  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
385  * }
386  * ~~~~~~~~~~
387  *
388  * @param as The aerospike instance to use for this operation.
389  * @param err The as_error to be populated if an error occurs.
390  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
391  * @param key The key of the record.
392  * @param ldt The LDT bin to operate on
393  * @param ldt_capacity The LDT Capacity, in terms of elements, not bytes.
394  *
395  * @return AEROSPIKE_OK if successful. Otherwise an error.
396  *
397  * @ingroup ldt_operations
398  */
400  aerospike * as, as_error * err, const as_policy_apply * policy,
401  const as_key * key, const as_ldt * ldt,
402  uint32_t *ldt_capacity
403  );
404 
405 /**
406  * Check to see if an LDT object exists in this record bin.
407  *
408  * ~~~~~~~~~~{.c}
409  * as_key key;
410  * as_key_init(&key, "myns", "myset", "mykey");
411  *
412  * as_ldt lmap;
413  * as_ldt_init(&lmap, "mylmap", AS_LDT_LMAP, NULL);
414  * uint32_t ldt_exists = 0;
415  *
416  * if ( aerospike_lmap_ldt_exists(&as, &err, NULL, &key, &lmap, &ldt_exists) != AEROSPIKE_OK ) {
417  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
418  * }
419  * ~~~~~~~~~~
420  *
421  * @param as The aerospike instance to use for this operation.
422  * @param err The as_error to be populated if an error occurs.
423  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
424  * @param key The key of the record.
425  * @param ldt The LDT to operate on. If not an LMAP bin, will return error.
426  * @param ldt_exists Ptr to as_boolean: Set to TRUE if ldt exists, otherwise false.
427  *
428  * @return AEROSPIKE_OK if successful. Otherwise an error.
429  *
430  * @ingroup ldt_operations
431  */
433  aerospike * as, as_error * err, const as_policy_apply * policy,
434  const as_key * key, const as_ldt * ldt,
435  as_boolean *ldt_exists
436  );
437 
438 
439 #ifdef __cplusplus
440 } // end extern "C"
441 #endif