All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
aerospike_key.h
Go to the documentation of this file.
1 /******************************************************************************
2  * Copyright 2008-2013 by Aerospike.
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining a copy
5  * of this software and associated documentation files (the "Software"), to
6  * deal in the Software without restriction, including without limitation the
7  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
8  * sell copies of the Software, and to permit persons to whom the Software is
9  * furnished to do so, subject to the following conditions:
10  *
11  * The above copyright notice and this permission notice shall be included in
12  * all copies or substantial portions of the Software.
13  *
14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
19  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
20  * IN THE SOFTWARE.
21  *****************************************************************************/
22 
23 /**
24  * @defgroup key_operations Key Operations
25  * @ingroup client_operations
26  *
27  * Aerospike provides a key based API to access and modify data into the
28  * cluster.
29  *
30  * The Key API is a collection of APIs that use as_key as for looking up
31  * records for accessing and modifying in the cluster.
32  *
33  */
34 
35 #pragma once
36 
37 #include <aerospike/aerospike.h>
38 #include <aerospike/as_error.h>
39 #include <aerospike/as_key.h>
40 #include <aerospike/as_list.h>
42 #include <aerospike/as_policy.h>
43 #include <aerospike/as_record.h>
44 #include <aerospike/as_status.h>
45 #include <aerospike/as_val.h>
46 
47 /******************************************************************************
48  * FUNCTIONS
49  *****************************************************************************/
50 
51 /**
52  * Look up a record by key, then return all bins.
53  *
54  * ~~~~~~~~~~{.c}
55  * as_key key;
56  * as_key_init(&key, "ns", "set", "key");
57  *
58  * as_record * rec = NULL;
59  * if ( aerospike_key_get(&as, &err, NULL, &key, &rec) != AEROSPIKE_OK ) {
60  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
61  * }
62  * else {
63  * as_record_destroy(rec);
64  * }
65  * ~~~~~~~~~~
66  *
67  * @param as The aerospike instance to use for this operation.
68  * @param err The as_error to be populated if an error occurs.
69  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
70  * @param key The key of the record.
71  * @param rec The record to be populated with the data from request.
72  *
73  * @return AEROSPIKE_OK if successful. Otherwise an error.
74  *
75  * @ingroup key_operations
76  */
78  aerospike * as, as_error * err, const as_policy_read * policy,
79  const as_key * key,
80  as_record ** rec
81  );
82 
83 /**
84  * Lookup a record by key, then return specified bins.
85  *
86  * ~~~~~~~~~~{.c}
87  * char * select[] = {"bin1", "bin2", "bin3", NULL};
88  *
89  * as_key key;
90  * as_key_init(&key, "ns", "set", "key");
91  *
92  * as_record * rec = NULL;
93  * if ( aerospike_key_select(&as, &err, NULL, &key, select, &rec) != AEROSPIKE_OK ) {
94  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
95  * }
96  * else {
97  * as_record_destroy(rec);
98  * }
99  * ~~~~~~~~~~
100  *
101  * @param as The aerospike instance to use for this operation.
102  * @param err The as_error to be populated if an error occurs.
103  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
104  * @param key The key of the record.
105  * @param bins The bins to select. A NULL terminated array of NULL terminated strings.
106  * @param rec The record to be populated with the data from request.
107  *
108  * @return AEROSPIKE_OK if successful. Otherwise an error.
109  *
110  * @ingroup key_operations
111  */
113  aerospike * as, as_error * err, const as_policy_read * policy,
114  const as_key * key, const char * bins[],
115  as_record ** rec
116  );
117 
118 /**
119  * Check if a record exists in the cluster via its key.
120  *
121  * ~~~~~~~~~~{.c}
122  * as_key key;
123  * as_key_init(&key, "ns", "set", "key");
124  *
125  * bool exists = true;
126  * if ( aerospike_key_exists(&as, &err, NULL, &key, &exists) != AEROSPIKE_OK ) {
127  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
128  * }
129  * else {
130  * fprintf(stdout, "Record %s", exists ? "exists." : "doesn't exist.");
131  * }
132  * ~~~~~~~~~~
133  *
134  * @param as The aerospike instance to use for this operation.
135  * @param err The as_error to be populated if an error occurs.
136  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
137  * @param key The key of the record.
138  * @param exists The variable to populate with `true` if the record exists, otherwise `false`.
139  *
140  * @return AEROSPIKE_OK if successful. Otherwise an error.
141  *
142  * @ingroup key_operations
143  */
145  aerospike * as, as_error * err, const as_policy_read * policy,
146  const as_key * key,
147  bool * exists
148  );
149 
150 /**
151  * Store a record in the cluster.
152  *
153  * ~~~~~~~~~~{.c}
154  * as_key key;
155  * as_key_init(&key, "ns", "set", "key");
156  *
157  * as_record rec;
158  * as_record_init(&rec, 2);
159  * as_record_set_str(&rec, "bin1", "abc");
160  * as_record_set_int64(&rec, "bin2", 123);
161  *
162  * if ( aerospike_key_put(&as, &err, NULL, &key, &rec) != AEROSPIKE_OK ) {
163  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
164  * }
165  *
166  * as_record_destroy(&rec);
167  * ~~~~~~~~~~
168  *
169  * @param as The aerospike instance to use for this operation.
170  * @param err The as_error to be populated if an error occurs.
171  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
172  * @param key The key of the record.
173  * @param rec The record containing the data to be written.
174  *
175  * @return AEROSPIKE_OK if successful. Otherwise an error.
176  *
177  * @ingroup key_operations
178  */
180  aerospike * as, as_error * err, const as_policy_write * policy,
181  const as_key * key, as_record * rec
182  );
183 
184 /**
185  * Remove a record from the cluster.
186  *
187  * ~~~~~~~~~~{.c}
188  * as_key key;
189  * as_key_init(&key, "ns", "set", "key");
190  *
191  * if ( aerospike_key_remove(&as, &err, NULL, &key) != AEROSPIKE_OK ) {
192  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
193  * }
194  * ~~~~~~~~~~
195  *
196  * @param as The aerospike instance to use for this operation.
197  * @param err The as_error to be populated if an error occurs.
198  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
199  * @param key The key of the record.
200  *
201  * @return AEROSPIKE_OK if successful. Otherwise an error.
202  *
203  * @ingroup key_operations
204  */
206  aerospike * as, as_error * err, const as_policy_remove * policy,
207  const as_key * key
208  );
209 
210 /**
211  * Lookup a record by key, then perform specified operations.
212  *
213  * ~~~~~~~~~~{.c}
214  * as_key key;
215  * as_key_init(&key, "ns", "set", "key");
216  *
217  * as_operations ops;
218  * as_operations_inita(&ops,3);
219  * as_operations_add_incr(&ops, "bin1", 456);
220  * as_operations_add_append_str(&ops, "bin2", "def");
221  * as_operations_add_read(&ops, "bin1")
222  *
223  * as_record * rec = NULL;
224  *
225  * if ( aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec) != AEROSPIKE_OK ) {
226  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
227  * }
228  * else {
229  * as_record_destroy(rec);
230  * }
231  *
232  * as_operations_destroy(&ops);
233  * ~~~~~~~~~~
234  *
235  * @param as The aerospike instance to use for this operation.
236  * @param err The as_error to be populated if an error occurs.
237  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
238  * @param key The key of the record.
239  * @param ops The operations to perform on the record.
240  * @param rec The record to be populated with the data from AS_OPERATOR_READ operations.
241  *
242  * @return AEROSPIKE_OK if successful. Otherwise an error.
243  *
244  * @ingroup key_operations
245  */
247  aerospike * as, as_error * err, const as_policy_operate * policy,
248  const as_key * key, const as_operations * ops,
249  as_record ** rec
250  );
251 
252 /**
253  * Lookup a record by key, then apply the UDF.
254  *
255  * ~~~~~~~~~~{.c}
256  * as_key key;
257  * as_key_init(&key, "ns", "set", "key");
258  *
259  * as_arraylist args;
260  * as_arraylist_inita(&args, 2);
261  * as_arraylist_append_int64(&args, 1);
262  * as_arraylist_append_int64(&args, 2);
263  *
264  * as_val * res = NULL;
265  *
266  * if ( aerospike_key_apply(&as, &err, NULL, &key, "math", "add", &args, &res) != AEROSPIKE_OK ) {
267  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
268  * }
269  * else {
270  * as_val_destroy(res);
271  * }
272  *
273  * as_arraylist_destroy(&args);
274  * ~~~~~~~~~~
275  *
276  *
277  * @param as The aerospike instance to use for this operation.
278  * @param err The as_error to be populated if an error occurs.
279  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
280  * @param key The key of the record.
281  * @param module The module containing the function to execute.
282  * @param function The function to execute.
283  * @param arglist The arguments for the function.
284  * @param result The return value from the function.
285  *
286  * @return AEROSPIKE_OK if successful. Otherwise an error.
287  *
288  * @ingroup key_operations
289  */
291  aerospike * as, as_error * err, const as_policy_apply * policy,
292  const as_key * key,
293  const char * module, const char * function, as_list * arglist,
294  as_val ** result
295  );
as_status aerospike_key_put(aerospike *as, as_error *err, const as_policy_write *policy, const as_key *key, as_record *rec)
as_status
Definition: as_status.h:32
as_status aerospike_key_get(aerospike *as, as_error *err, const as_policy_read *policy, const as_key *key, as_record **rec)
as_status aerospike_key_operate(aerospike *as, as_error *err, const as_policy_operate *policy, const as_key *key, const as_operations *ops, as_record **rec)
Definition: as_val.h:56
as_status aerospike_key_apply(aerospike *as, as_error *err, const as_policy_apply *policy, const as_key *key, const char *module, const char *function, as_list *arglist, as_val **result)
as_status aerospike_key_select(aerospike *as, as_error *err, const as_policy_read *policy, const as_key *key, const char *bins[], as_record **rec)
as_status aerospike_key_remove(aerospike *as, as_error *err, const as_policy_remove *policy, const as_key *key)
Definition: as_key.h:199
as_status aerospike_key_exists(aerospike *as, as_error *err, const as_policy_read *policy, const as_key *key, bool *exists)