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-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
*/
77
as_status
aerospike_key_get
(
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
*/
112
as_status
aerospike_key_select
(
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
*/
144
as_status
aerospike_key_exists
(
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
*/
179
as_status
aerospike_key_put
(
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
*/
205
as_status
aerospike_key_remove
(
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
*/
246
as_status
aerospike_key_operate
(
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
*/
290
as_status
aerospike_key_apply
(
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
);