Main Page
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Friends
Macros
Groups
Pages
aerospike
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
>
35
#include <
aerospike/as_operations.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
*/
75
as_status
aerospike_key_get
(
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
*/
110
as_status
aerospike_key_select
(
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
*/
143
as_status
aerospike_key_exists
(
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
*/
178
as_status
aerospike_key_put
(
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
*/
204
as_status
aerospike_key_remove
(
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
*/
245
as_status
aerospike_key_operate
(
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
*/
289
as_status
aerospike_key_apply
(
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
301
aerospike_has_double
(
aerospike
* as);
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
308
aerospike_has_geo
(
aerospike
* as);
309
310
#ifdef __cplusplus
311
}
// end extern "C"
312
#endif