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-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  * @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 /******************************************************************************
42  * FUNCTIONS
43  *****************************************************************************/
44 
45 /**
46  * Look up a record by key, then return all bins.
47  *
48  * ~~~~~~~~~~{.c}
49  * as_key key;
50  * as_key_init(&key, "ns", "set", "key");
51  *
52  * as_record * rec = NULL;
53  * if ( aerospike_key_get(&as, &err, NULL, &key, &rec) != AEROSPIKE_OK ) {
54  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
55  * }
56  * else {
57  * as_record_destroy(rec);
58  * }
59  * ~~~~~~~~~~
60  *
61  * @param as The aerospike instance to use for this operation.
62  * @param err The as_error to be populated if an error occurs.
63  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
64  * @param key The key of the record.
65  * @param rec The record to be populated with the data from request.
66  *
67  * @return AEROSPIKE_OK if successful. Otherwise an error.
68  *
69  * @ingroup key_operations
70  */
72  aerospike * as, as_error * err, const as_policy_read * policy,
73  const as_key * key,
74  as_record ** rec
75  );
76 
77 /**
78  * Lookup a record by key, then return specified bins.
79  *
80  * ~~~~~~~~~~{.c}
81  * char * select[] = {"bin1", "bin2", "bin3", NULL};
82  *
83  * as_key key;
84  * as_key_init(&key, "ns", "set", "key");
85  *
86  * as_record * rec = NULL;
87  * if ( aerospike_key_select(&as, &err, NULL, &key, select, &rec) != AEROSPIKE_OK ) {
88  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
89  * }
90  * else {
91  * as_record_destroy(rec);
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 bins The bins to select. A NULL terminated array of NULL terminated strings.
100  * @param rec The record to be populated with the data from request.
101  *
102  * @return AEROSPIKE_OK if successful. Otherwise an error.
103  *
104  * @ingroup key_operations
105  */
107  aerospike * as, as_error * err, const as_policy_read * policy,
108  const as_key * key, const char * bins[],
109  as_record ** rec
110  );
111 
112 /**
113  * Check if a record exists in the cluster via its key. The record's metadata
114  * will be populated if the record exists.
115  *
116  * ~~~~~~~~~~{.c}
117  * as_key key;
118  * as_key_init(&key, "ns", "set", "key");
119  *
120  * bool exists = true;
121  * if ( aerospike_key_exists(&as, &err, NULL, &key, &rec) != AEROSPIKE_OK ) {
122  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
123  * }
124  * else {
125  * fprintf(stdout, "Record %s", exists ? "exists." : "doesn't exist.");
126  * }
127  * ~~~~~~~~~~
128  *
129  * @param as The aerospike instance to use for this operation.
130  * @param err The as_error to be populated if an error occurs.
131  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
132  * @param key The key of the record.
133  * @param rec The metadata will be populated if the record exists.
134  *
135  * @return AEROSPIKE_OK if successful. AEROSPIKE_ERR_RECORD_NOT_FOUND if not found. Otherwise an error.
136  *
137  * @ingroup key_operations
138  */
140  aerospike * as, as_error * err, const as_policy_read * policy,
141  const as_key * key,
142  as_record ** rec
143  );
144 
145 /**
146  * Store a record in the cluster.
147  *
148  * ~~~~~~~~~~{.c}
149  * as_key key;
150  * as_key_init(&key, "ns", "set", "key");
151  *
152  * as_record rec;
153  * as_record_init(&rec, 2);
154  * as_record_set_str(&rec, "bin1", "abc");
155  * as_record_set_int64(&rec, "bin2", 123);
156  *
157  * if ( aerospike_key_put(&as, &err, NULL, &key, &rec) != AEROSPIKE_OK ) {
158  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
159  * }
160  *
161  * as_record_destroy(&rec);
162  * ~~~~~~~~~~
163  *
164  * @param as The aerospike instance to use for this operation.
165  * @param err The as_error to be populated if an error occurs.
166  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
167  * @param key The key of the record.
168  * @param rec The record containing the data to be written.
169  *
170  * @return AEROSPIKE_OK if successful. Otherwise an error.
171  *
172  * @ingroup key_operations
173  */
175  aerospike * as, as_error * err, const as_policy_write * policy,
176  const as_key * key, as_record * rec
177  );
178 
179 /**
180  * Remove a record from the cluster.
181  *
182  * ~~~~~~~~~~{.c}
183  * as_key key;
184  * as_key_init(&key, "ns", "set", "key");
185  *
186  * if ( aerospike_key_remove(&as, &err, NULL, &key) != AEROSPIKE_OK ) {
187  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
188  * }
189  * ~~~~~~~~~~
190  *
191  * @param as The aerospike instance to use for this operation.
192  * @param err The as_error to be populated if an error occurs.
193  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
194  * @param key The key of the record.
195  *
196  * @return AEROSPIKE_OK if successful. Otherwise an error.
197  *
198  * @ingroup key_operations
199  */
201  aerospike * as, as_error * err, const as_policy_remove * policy,
202  const as_key * key
203  );
204 
205 /**
206  * Lookup a record by key, then perform specified operations.
207  *
208  * ~~~~~~~~~~{.c}
209  * as_key key;
210  * as_key_init(&key, "ns", "set", "key");
211  *
212  * as_operations ops;
213  * as_operations_inita(&ops,3);
214  * as_operations_add_incr(&ops, "bin1", 456);
215  * as_operations_add_append_str(&ops, "bin2", "def");
216  * as_operations_add_read(&ops, "bin1")
217  *
218  * as_record * rec = NULL;
219  *
220  * if ( aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec) != AEROSPIKE_OK ) {
221  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
222  * }
223  * else {
224  * as_record_destroy(rec);
225  * }
226  *
227  * as_operations_destroy(&ops);
228  * ~~~~~~~~~~
229  *
230  * @param as The aerospike instance to use for this operation.
231  * @param err The as_error to be populated if an error occurs.
232  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
233  * @param key The key of the record.
234  * @param ops The operations to perform on the record.
235  * @param rec The record to be populated with the data from AS_OPERATOR_READ operations.
236  *
237  * @return AEROSPIKE_OK if successful. Otherwise an error.
238  *
239  * @ingroup key_operations
240  */
242  aerospike * as, as_error * err, const as_policy_operate * policy,
243  const as_key * key, const as_operations * ops,
244  as_record ** rec
245  );
246 
247 /**
248  * Lookup a record by key, then apply the UDF.
249  *
250  * ~~~~~~~~~~{.c}
251  * as_key key;
252  * as_key_init(&key, "ns", "set", "key");
253  *
254  * as_arraylist args;
255  * as_arraylist_inita(&args, 2);
256  * as_arraylist_append_int64(&args, 1);
257  * as_arraylist_append_int64(&args, 2);
258  *
259  * as_val * res = NULL;
260  *
261  * if ( aerospike_key_apply(&as, &err, NULL, &key, "math", "add", &args, &res) != AEROSPIKE_OK ) {
262  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
263  * }
264  * else {
265  * as_val_destroy(res);
266  * }
267  *
268  * as_arraylist_destroy(&args);
269  * ~~~~~~~~~~
270  *
271  *
272  * @param as The aerospike instance to use for this operation.
273  * @param err The as_error to be populated if an error occurs.
274  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
275  * @param key The key of the record.
276  * @param module The module containing the function to execute.
277  * @param function The function to execute.
278  * @param arglist The arguments for the function.
279  * @param result The return value from the function.
280  *
281  * @return AEROSPIKE_OK if successful. Otherwise an error.
282  *
283  * @ingroup key_operations
284  */
286  aerospike * as, as_error * err, const as_policy_apply * policy,
287  const as_key * key,
288  const char * module, const char * function, as_list * arglist,
289  as_val ** result
290  );
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:26
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:51
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)
Definition: as_key.h:193