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-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
>
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
/******************************************************************************
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
*/
71
as_status
aerospike_key_get
(
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
*/
106
as_status
aerospike_key_select
(
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
*/
139
as_status
aerospike_key_exists
(
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
*/
174
as_status
aerospike_key_put
(
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
*/
200
as_status
aerospike_key_remove
(
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
*/
241
as_status
aerospike_key_operate
(
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
*/
285
as_status
aerospike_key_apply
(
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
);