All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
target/Darwin-i386/include/aerospike/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>
41 #include <aerospike/as_operations.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. The record's metadata
120  * will be populated if the record exists.
121  *
122  * ~~~~~~~~~~{.c}
123  * as_key key;
124  * as_key_init(&key, "ns", "set", "key");
125  *
126  * bool exists = true;
127  * if ( aerospike_key_exists(&as, &err, NULL, &key, &rec) != AEROSPIKE_OK ) {
128  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
129  * }
130  * else {
131  * fprintf(stdout, "Record %s", exists ? "exists." : "doesn't exist.");
132  * }
133  * ~~~~~~~~~~
134  *
135  * @param as The aerospike instance to use for this operation.
136  * @param err The as_error to be populated if an error occurs.
137  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
138  * @param key The key of the record.
139  * @param rec The metadata will be populated if the record exists.
140  *
141  * @return AEROSPIKE_OK if successful. AEROSPIKE_ERR_RECORD_NOT_FOUND if not found. Otherwise an error.
142  *
143  * @ingroup key_operations
144  */
146  aerospike * as, as_error * err, const as_policy_read * policy,
147  const as_key * key,
148  as_record ** rec
149  );
150 
151 /**
152  * Store a record in the cluster.
153  *
154  * ~~~~~~~~~~{.c}
155  * as_key key;
156  * as_key_init(&key, "ns", "set", "key");
157  *
158  * as_record rec;
159  * as_record_init(&rec, 2);
160  * as_record_set_str(&rec, "bin1", "abc");
161  * as_record_set_int64(&rec, "bin2", 123);
162  *
163  * if ( aerospike_key_put(&as, &err, NULL, &key, &rec) != AEROSPIKE_OK ) {
164  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
165  * }
166  *
167  * as_record_destroy(&rec);
168  * ~~~~~~~~~~
169  *
170  * @param as The aerospike instance to use for this operation.
171  * @param err The as_error to be populated if an error occurs.
172  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
173  * @param key The key of the record.
174  * @param rec The record containing the data to be written.
175  *
176  * @return AEROSPIKE_OK if successful. Otherwise an error.
177  *
178  * @ingroup key_operations
179  */
181  aerospike * as, as_error * err, const as_policy_write * policy,
182  const as_key * key, as_record * rec
183  );
184 
185 /**
186  * Remove a record from the cluster.
187  *
188  * ~~~~~~~~~~{.c}
189  * as_key key;
190  * as_key_init(&key, "ns", "set", "key");
191  *
192  * if ( aerospike_key_remove(&as, &err, NULL, &key) != AEROSPIKE_OK ) {
193  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
194  * }
195  * ~~~~~~~~~~
196  *
197  * @param as The aerospike instance to use for this operation.
198  * @param err The as_error to be populated if an error occurs.
199  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
200  * @param key The key of the record.
201  *
202  * @return AEROSPIKE_OK if successful. Otherwise an error.
203  *
204  * @ingroup key_operations
205  */
207  aerospike * as, as_error * err, const as_policy_remove * policy,
208  const as_key * key
209  );
210 
211 /**
212  * Lookup a record by key, then perform specified operations.
213  *
214  * ~~~~~~~~~~{.c}
215  * as_key key;
216  * as_key_init(&key, "ns", "set", "key");
217  *
218  * as_operations ops;
219  * as_operations_inita(&ops,3);
220  * as_operations_add_incr(&ops, "bin1", 456);
221  * as_operations_add_append_str(&ops, "bin2", "def");
222  * as_operations_add_read(&ops, "bin1")
223  *
224  * as_record * rec = NULL;
225  *
226  * if ( aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec) != AEROSPIKE_OK ) {
227  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
228  * }
229  * else {
230  * as_record_destroy(rec);
231  * }
232  *
233  * as_operations_destroy(&ops);
234  * ~~~~~~~~~~
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 ops The operations to perform on the record.
241  * @param rec The record to be populated with the data from AS_OPERATOR_READ operations.
242  *
243  * @return AEROSPIKE_OK if successful. Otherwise an error.
244  *
245  * @ingroup key_operations
246  */
248  aerospike * as, as_error * err, const as_policy_operate * policy,
249  const as_key * key, const as_operations * ops,
250  as_record ** rec
251  );
252 
253 /**
254  * Lookup a record by key, then apply the UDF.
255  *
256  * ~~~~~~~~~~{.c}
257  * as_key key;
258  * as_key_init(&key, "ns", "set", "key");
259  *
260  * as_arraylist args;
261  * as_arraylist_inita(&args, 2);
262  * as_arraylist_append_int64(&args, 1);
263  * as_arraylist_append_int64(&args, 2);
264  *
265  * as_val * res = NULL;
266  *
267  * if ( aerospike_key_apply(&as, &err, NULL, &key, "math", "add", &args, &res) != AEROSPIKE_OK ) {
268  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
269  * }
270  * else {
271  * as_val_destroy(res);
272  * }
273  *
274  * as_arraylist_destroy(&args);
275  * ~~~~~~~~~~
276  *
277  *
278  * @param as The aerospike instance to use for this operation.
279  * @param err The as_error to be populated if an error occurs.
280  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
281  * @param key The key of the record.
282  * @param module The module containing the function to execute.
283  * @param function The function to execute.
284  * @param arglist The arguments for the function.
285  * @param result The return value from the function.
286  *
287  * @return AEROSPIKE_OK if successful. Otherwise an error.
288  *
289  * @ingroup key_operations
290  */
292  aerospike * as, as_error * err, const as_policy_apply * policy,
293  const as_key * key,
294  const char * module, const char * function, as_list * arglist,
295  as_val ** result
296  );
as_status aerospike_key_put(aerospike *as, as_error *err, const as_policy_write *policy, const as_key *key, as_record *rec)
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)
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_exists(aerospike *as, as_error *err, const as_policy_read *policy, const as_key *key, as_record **rec)
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)