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-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 /**
20  * @defgroup key_operations Key Operations
21  * @ingroup client_operations
22  *
23  * Aerospike provides a key based API to access and modify data into the
24  * cluster.
25  *
26  * The Key API is a collection of APIs that use as_key as for looking up
27  * records for accessing and modifying in the cluster.
28  *
29  */
30 
31 #include <aerospike/aerospike.h>
32 #include <aerospike/as_error.h>
33 #include <aerospike/as_key.h>
34 #include <aerospike/as_list.h>
36 #include <aerospike/as_policy.h>
37 #include <aerospike/as_record.h>
38 #include <aerospike/as_status.h>
39 #include <aerospike/as_val.h>
40 
41 #ifdef __cplusplus
42 extern "C" {
43 #endif
44 
45 /******************************************************************************
46  * FUNCTIONS
47  *****************************************************************************/
48 
49 /**
50  * Look up a record by key, then return all bins.
51  *
52  * ~~~~~~~~~~{.c}
53  * as_key key;
54  * as_key_init(&key, "ns", "set", "key");
55  *
56  * as_record * rec = NULL;
57  * if ( aerospike_key_get(&as, &err, NULL, &key, &rec) != AEROSPIKE_OK ) {
58  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
59  * }
60  * else {
61  * as_record_destroy(rec);
62  * }
63  * ~~~~~~~~~~
64  *
65  * @param as The aerospike instance to use for this operation.
66  * @param err The as_error to be populated if an error occurs.
67  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
68  * @param key The key of the record.
69  * @param rec The record to be populated with the data from request.
70  *
71  * @return AEROSPIKE_OK if successful. Otherwise an error.
72  *
73  * @ingroup key_operations
74  */
76  aerospike * as, as_error * err, const as_policy_read * policy,
77  const as_key * key,
78  as_record ** rec
79  );
80 
81 /**
82  * Lookup a record by key, then return specified bins.
83  *
84  * ~~~~~~~~~~{.c}
85  * char * select[] = {"bin1", "bin2", "bin3", NULL};
86  *
87  * as_key key;
88  * as_key_init(&key, "ns", "set", "key");
89  *
90  * as_record * rec = NULL;
91  * if ( aerospike_key_select(&as, &err, NULL, &key, select, &rec) != AEROSPIKE_OK ) {
92  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
93  * }
94  * else {
95  * as_record_destroy(rec);
96  * }
97  * ~~~~~~~~~~
98  *
99  * @param as The aerospike instance to use for this operation.
100  * @param err The as_error to be populated if an error occurs.
101  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
102  * @param key The key of the record.
103  * @param bins The bins to select. A NULL terminated array of NULL terminated strings.
104  * @param rec The record to be populated with the data from request.
105  *
106  * @return AEROSPIKE_OK if successful. Otherwise an error.
107  *
108  * @ingroup key_operations
109  */
111  aerospike * as, as_error * err, const as_policy_read * policy,
112  const as_key * key, const char * bins[],
113  as_record ** rec
114  );
115 
116 /**
117  * Check if a record exists in the cluster via its key. The record's metadata
118  * will be populated if the record exists.
119  *
120  * ~~~~~~~~~~{.c}
121  * as_key key;
122  * as_key_init(&key, "ns", "set", "key");
123  *
124  * bool exists = true;
125  * if ( aerospike_key_exists(&as, &err, NULL, &key, &rec) != AEROSPIKE_OK ) {
126  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
127  * }
128  * else {
129  * fprintf(stdout, "Record %s", exists ? "exists." : "doesn't exist.");
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 rec The metadata will be populated if the record exists.
138  *
139  * @return AEROSPIKE_OK if successful. AEROSPIKE_ERR_RECORD_NOT_FOUND if not found. Otherwise an error.
140  *
141  * @ingroup key_operations
142  */
144  aerospike * as, as_error * err, const as_policy_read * policy,
145  const as_key * key,
146  as_record ** rec
147  );
148 
149 /**
150  * Store a record in the cluster.
151  *
152  * ~~~~~~~~~~{.c}
153  * as_key key;
154  * as_key_init(&key, "ns", "set", "key");
155  *
156  * as_record rec;
157  * as_record_init(&rec, 2);
158  * as_record_set_str(&rec, "bin1", "abc");
159  * as_record_set_int64(&rec, "bin2", 123);
160  *
161  * if ( aerospike_key_put(&as, &err, NULL, &key, &rec) != AEROSPIKE_OK ) {
162  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
163  * }
164  *
165  * as_record_destroy(&rec);
166  * ~~~~~~~~~~
167  *
168  * @param as The aerospike instance to use for this operation.
169  * @param err The as_error to be populated if an error occurs.
170  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
171  * @param key The key of the record.
172  * @param rec The record containing the data to be written.
173  *
174  * @return AEROSPIKE_OK if successful. Otherwise an error.
175  *
176  * @ingroup key_operations
177  */
179  aerospike * as, as_error * err, const as_policy_write * policy,
180  const as_key * key, as_record * rec
181  );
182 
183 /**
184  * Remove a record from the cluster.
185  *
186  * ~~~~~~~~~~{.c}
187  * as_key key;
188  * as_key_init(&key, "ns", "set", "key");
189  *
190  * if ( aerospike_key_remove(&as, &err, NULL, &key) != AEROSPIKE_OK ) {
191  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
192  * }
193  * ~~~~~~~~~~
194  *
195  * @param as The aerospike instance to use for this operation.
196  * @param err The as_error to be populated if an error occurs.
197  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
198  * @param key The key of the record.
199  *
200  * @return AEROSPIKE_OK if successful and AEROSPIKE_ERR_RECORD_NOT_FOUND if the record was not found. Otherwise an error.
201  *
202  * @ingroup key_operations
203  */
205  aerospike * as, as_error * err, const as_policy_remove * policy,
206  const as_key * key
207  );
208 
209 /**
210  * Lookup a record by key, then perform specified operations.
211  *
212  * ~~~~~~~~~~{.c}
213  * as_key key;
214  * as_key_init(&key, "ns", "set", "key");
215  *
216  * as_operations ops;
217  * as_operations_inita(&ops,3);
218  * as_operations_add_incr(&ops, "bin1", 456);
219  * as_operations_add_append_str(&ops, "bin2", "def");
220  * as_operations_add_read(&ops, "bin1")
221  *
222  * as_record * rec = NULL;
223  *
224  * if ( aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec) != AEROSPIKE_OK ) {
225  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
226  * }
227  * else {
228  * as_record_destroy(rec);
229  * }
230  *
231  * as_operations_destroy(&ops);
232  * ~~~~~~~~~~
233  *
234  * @param as The aerospike instance to use for this operation.
235  * @param err The as_error to be populated if an error occurs.
236  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
237  * @param key The key of the record.
238  * @param ops The operations to perform on the record.
239  * @param rec The record to be populated with the data from AS_OPERATOR_READ operations.
240  *
241  * @return AEROSPIKE_OK if successful. Otherwise an error.
242  *
243  * @ingroup key_operations
244  */
246  aerospike * as, as_error * err, const as_policy_operate * policy,
247  const as_key * key, const as_operations * ops,
248  as_record ** rec
249  );
250 
251 /**
252  * Lookup a record by key, then apply the UDF.
253  *
254  * ~~~~~~~~~~{.c}
255  * as_key key;
256  * as_key_init(&key, "ns", "set", "key");
257  *
258  * as_arraylist args;
259  * as_arraylist_inita(&args, 2);
260  * as_arraylist_append_int64(&args, 1);
261  * as_arraylist_append_int64(&args, 2);
262  *
263  * as_val * res = NULL;
264  *
265  * if ( aerospike_key_apply(&as, &err, NULL, &key, "math", "add", &args, &res) != AEROSPIKE_OK ) {
266  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
267  * }
268  * else {
269  * as_val_destroy(res);
270  * }
271  *
272  * as_arraylist_destroy(&args);
273  * ~~~~~~~~~~
274  *
275  *
276  * @param as The aerospike instance to use for this operation.
277  * @param err The as_error to be populated if an error occurs.
278  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
279  * @param key The key of the record.
280  * @param module The module containing the function to execute.
281  * @param function The function to execute.
282  * @param arglist The arguments for the function.
283  * @param result The return value from the function.
284  *
285  * @return AEROSPIKE_OK if successful. Otherwise an error.
286  *
287  * @ingroup key_operations
288  */
290  aerospike * as, as_error * err, const as_policy_apply * policy,
291  const as_key * key,
292  const char * module, const char * function, as_list * arglist,
293  as_val ** result
294  );
295 
296 /**
297  * Do the connected servers support the new floating point type.
298  * The cluster must already be connected (aerospike_connect()) prior to making this call.
299  */
300 bool
302 
303 /**
304  * Do the connected servers support geospatial data and queries.
305  * The cluster must already be connected (aerospike_connect()) prior to making this call.
306  */
307 bool
309 
310 #ifdef __cplusplus
311 } // end extern "C"
312 #endif