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-2016 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_listener.h
>
33
#include <
aerospike/as_error.h
>
34
#include <
aerospike/as_key.h
>
35
#include <
aerospike/as_list.h
>
36
#include <
aerospike/as_operations.h
>
37
#include <
aerospike/as_policy.h
>
38
#include <
aerospike/as_record.h
>
39
#include <
aerospike/as_status.h
>
40
#include <
aerospike/as_val.h
>
41
42
#ifdef __cplusplus
43
extern
"C"
{
44
#endif
45
46
/******************************************************************************
47
* FUNCTIONS
48
*****************************************************************************/
49
50
/**
51
* Look up a record by key and return all bins.
52
*
53
* ~~~~~~~~~~{.c}
54
* as_key key;
55
* as_key_init(&key, "ns", "set", "key");
56
*
57
* as_record* rec = NULL;
58
* if (aerospike_key_get(&as, &err, NULL, &key, &rec) != AEROSPIKE_OK) {
59
* printf("error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
60
* }
61
* else {
62
* as_record_destroy(rec);
63
* }
64
* ~~~~~~~~~~
65
*
66
* @param as The aerospike instance to use for this operation.
67
* @param err The as_error to be populated if an error occurs.
68
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
69
* @param key The key of the record.
70
* @param rec The record to be populated with the data from request.
71
*
72
* @return AEROSPIKE_OK if successful. Otherwise an error.
73
*
74
* @ingroup key_operations
75
*/
76
as_status
77
aerospike_key_get
(
78
aerospike
* as,
as_error
* err,
const
as_policy_read
* policy,
const
as_key
* key,
as_record
** rec
79
);
80
81
/**
82
* Asynchronously look up a record by key and return all bins.
83
*
84
* ~~~~~~~~~~{.c}
85
* void my_listener(as_error* err, as_record* record, void* udata, as_event_loop* event_loop)
86
* {
87
* if (err) {
88
* printf("Command failed: %d %s\n", err->code, err->message);
89
* return;
90
* }
91
* // Process record bins
92
* // Do not call as_record_destroy() because the calling function will do that for you.
93
* }
94
*
95
* as_key key;
96
* as_key_init(&key, "ns", "set", "key");
97
*
98
* as_status status = aerospike_key_get_async(&as, &err, NULL, &key, my_listener, NULL, NULL, false);
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 listener User function to be called with command results.
106
* @param udata User data to be forwarded to user callback.
107
* @param event_loop Event loop assigned to run this command. If NULL, an event loop will be choosen by round-robin.
108
* @param pipeline Should responses be combined with other responses before sending back to client.
109
*
110
* @return AEROSPIKE_OK if async command succesfully queued. Otherwise an error.
111
*
112
* @ingroup key_operations
113
*/
114
as_status
115
aerospike_key_get_async
(
116
aerospike
* as,
as_error
* err,
const
as_policy_read
* policy,
const
as_key
* key,
117
as_async_record_listener
listener,
void
* udata,
as_event_loop
* event_loop,
bool
pipeline
118
);
119
120
/**
121
* Lookup a record by key, then return specified bins.
122
*
123
* ~~~~~~~~~~{.c}
124
* char* select[] = {"bin1", "bin2", "bin3", NULL};
125
*
126
* as_key key;
127
* as_key_init(&key, "ns", "set", "key");
128
*
129
* as_record* rec = NULL;
130
* if (aerospike_key_select(&as, &err, NULL, &key, select, &rec) != AEROSPIKE_OK) {
131
* printf("error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
132
* }
133
* else {
134
* as_record_destroy(rec);
135
* }
136
* ~~~~~~~~~~
137
*
138
* @param as The aerospike instance to use for this operation.
139
* @param err The as_error to be populated if an error occurs.
140
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
141
* @param key The key of the record.
142
* @param bins The bins to select. A NULL terminated array of NULL terminated strings.
143
* @param rec The record to be populated with the data from request.
144
*
145
* @return AEROSPIKE_OK if successful. Otherwise an error.
146
*
147
* @ingroup key_operations
148
*/
149
as_status
150
aerospike_key_select
(
151
aerospike
* as,
as_error
* err,
const
as_policy_read
* policy,
const
as_key
* key,
152
const
char
* bins[],
as_record
** rec
153
);
154
155
/**
156
* Asynchronously lookup a record by key, then return specified bins.
157
*
158
* ~~~~~~~~~~{.c}
159
* void my_listener(as_error* err, as_record* record, void* udata, as_event_loop* event_loop)
160
* {
161
* if (err) {
162
* printf("Command failed: %d %s\n", err->code, err->message);
163
* return;
164
* }
165
* // Process record bins
166
* // Do not call as_record_destroy() because the calling function will do that for you.
167
* }
168
*
169
* char* select[] = {"bin1", "bin2", "bin3", NULL};
170
*
171
* as_key key;
172
* as_key_init(&key, "ns", "set", "key");
173
*
174
* as_status status = aerospike_key_select_async(&as, &err, NULL, &key, select, my_listener, NULL, NULL, false);
175
* ~~~~~~~~~~
176
*
177
* @param as The aerospike instance to use for this operation.
178
* @param err The as_error to be populated if an error occurs.
179
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
180
* @param key The key of the record.
181
* @param bins The bins to select. A NULL terminated array of NULL terminated strings.
182
* @param listener User function to be called with command results.
183
* @param udata User data to be forwarded to user callback.
184
* @param event_loop Event loop assigned to run this command. If NULL, an event loop will be choosen by round-robin.
185
* @param pipeline Should responses be combined with other responses before sending back to client.
186
*
187
* @return AEROSPIKE_OK if async command succesfully queued. Otherwise an error.
188
*
189
* @ingroup key_operations
190
*/
191
as_status
192
aerospike_key_select_async
(
193
aerospike
* as,
as_error
* err,
const
as_policy_read
* policy,
const
as_key
* key,
const
char
* bins[],
194
as_async_record_listener
listener,
void
* udata,
as_event_loop
* event_loop,
bool
pipeline
195
);
196
197
/**
198
* Check if a record exists in the cluster via its key. The record's metadata
199
* will be populated if the record exists.
200
*
201
* ~~~~~~~~~~{.c}
202
* as_key key;
203
* as_key_init(&key, "ns", "set", "key");
204
*
205
* as_record* rec = NULL;
206
* if (aerospike_key_exists(&as, &err, NULL, &key, &rec) != AEROSPIKE_OK) {
207
* printf("error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
208
* }
209
* else {
210
* if (rec) {
211
* printf("Record exists.");
212
* as_record_destroy(rec);
213
* }
214
* else {
215
* printf("Record doesn't exist.");
216
* }
217
* }
218
* ~~~~~~~~~~
219
*
220
* @param as The aerospike instance to use for this operation.
221
* @param err The as_error to be populated if an error occurs.
222
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
223
* @param key The key of the record.
224
* @param rec The metadata will be populated if the record exists.
225
*
226
* @return AEROSPIKE_OK if successful. AEROSPIKE_ERR_RECORD_NOT_FOUND if not found. Otherwise an error.
227
*
228
* @ingroup key_operations
229
*/
230
as_status
231
aerospike_key_exists
(
232
aerospike
* as,
as_error
* err,
const
as_policy_read
* policy,
const
as_key
* key,
as_record
** rec
233
);
234
235
/**
236
* Asynchronously check if a record exists in the cluster via its key. The record's metadata
237
* will be populated if the record exists.
238
*
239
* ~~~~~~~~~~{.c}
240
* void my_listener(as_error* err, as_record* record, void* udata, as_event_loop* event_loop)
241
* {
242
* if (err) {
243
* printf("Command failed: %d %s\n", err->code, err->message);
244
* return;
245
* }
246
* if (record) {
247
* printf("Record exists.");
248
* // Do not call as_record_destroy() because the calling function will do that for you.
249
* }
250
* else {
251
* printf("Record doesn't exist.");
252
* }
253
* }
254
*
255
* as_key key;
256
* as_key_init(&key, "ns", "set", "key");
257
*
258
* as_status status = aerospike_key_exists_async(&as, &err, NULL, &key, my_listener, NULL, NULL, false);
259
* ~~~~~~~~~~
260
*
261
* @param as The aerospike instance to use for this operation.
262
* @param err The as_error to be populated if an error occurs.
263
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
264
* @param key The key of the record.
265
* @param listener User function to be called with command results.
266
* @param udata User data to be forwarded to user callback.
267
* @param event_loop Event loop assigned to run this command. If NULL, an event loop will be choosen by round-robin.
268
* @param pipeline Should responses be combined with other responses before sending back to client.
269
*
270
* @return AEROSPIKE_OK if async command succesfully queued. Otherwise an error.
271
*
272
* @ingroup key_operations
273
*/
274
as_status
275
aerospike_key_exists_async
(
276
aerospike
* as,
as_error
* err,
const
as_policy_read
* policy,
const
as_key
* key,
277
as_async_record_listener
listener,
void
* udata,
as_event_loop
* event_loop,
bool
pipeline
278
);
279
280
/**
281
* Store a record in the cluster.
282
*
283
* ~~~~~~~~~~{.c}
284
* as_key key;
285
* as_key_init(&key, "ns", "set", "key");
286
*
287
* as_record rec;
288
* as_record_init(&rec, 2);
289
* as_record_set_str(&rec, "bin1", "abc");
290
* as_record_set_int64(&rec, "bin2", 123);
291
*
292
* if (aerospike_key_put(&as, &err, NULL, &key, &rec) != AEROSPIKE_OK) {
293
* printf("error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
294
* }
295
* as_record_destroy(&rec);
296
* ~~~~~~~~~~
297
*
298
* @param as The aerospike instance to use for this operation.
299
* @param err The as_error to be populated if an error occurs.
300
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
301
* @param key The key of the record.
302
* @param rec The record containing the data to be written.
303
*
304
* @return AEROSPIKE_OK if successful. Otherwise an error.
305
*
306
* @ingroup key_operations
307
*/
308
as_status
309
aerospike_key_put
(
310
aerospike
* as,
as_error
* err,
const
as_policy_write
* policy,
const
as_key
* key,
as_record
* rec
311
);
312
313
/**
314
* Asynchronously store a record in the cluster.
315
*
316
* ~~~~~~~~~~{.c}
317
* void my_listener(as_error* err, void* udata, as_event_loop* event_loop)
318
* {
319
* if (err) {
320
* printf("Command failed: %d %s\n", err->code, err->message);
321
* return;
322
* }
323
* printf("Command succeeded\n");
324
* }
325
*
326
* as_key key;
327
* as_key_init(&key, "ns", "set", "key");
328
*
329
* as_record rec;
330
* as_record_init(&rec, 2);
331
* as_record_set_str(&rec, "bin1", "abc");
332
* as_record_set_int64(&rec, "bin2", 123);
333
*
334
* as_status status = aerospike_key_put_async(&as, &err, NULL, &key, &rec, my_listener, NULL, NULL, false);
335
* as_record_destroy(&rec);
336
* ~~~~~~~~~~
337
*
338
* @param as The aerospike instance to use for this operation.
339
* @param err The as_error to be populated if an error occurs.
340
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
341
* @param key The key of the record.
342
* @param rec The record containing the data to be written.
343
* @param listener User function to be called with command results.
344
* @param udata User data to be forwarded to user callback.
345
* @param event_loop Event loop assigned to run this command. If NULL, an event loop will be choosen by round-robin.
346
* @param pipeline Should responses be combined with other responses before sending back to client.
347
*
348
* @return AEROSPIKE_OK if async command succesfully queued. Otherwise an error.
349
*
350
* @ingroup key_operations
351
*/
352
as_status
353
aerospike_key_put_async
(
354
aerospike
* as,
as_error
* err,
const
as_policy_write
* policy,
const
as_key
* key,
as_record
* rec,
355
as_async_write_listener
listener,
void
* udata,
as_event_loop
* event_loop,
bool
pipeline
356
);
357
358
/**
359
* Remove a record from the cluster.
360
*
361
* ~~~~~~~~~~{.c}
362
* as_key key;
363
* as_key_init(&key, "ns", "set", "key");
364
*
365
* if (aerospike_key_remove(&as, &err, NULL, &key) != AEROSPIKE_OK) {
366
* printf("error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
367
* }
368
* ~~~~~~~~~~
369
*
370
* @param as The aerospike instance to use for this operation.
371
* @param err The as_error to be populated if an error occurs.
372
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
373
* @param key The key of the record.
374
*
375
* @return AEROSPIKE_OK if successful and AEROSPIKE_ERR_RECORD_NOT_FOUND if the record was not found. Otherwise an error.
376
*
377
* @ingroup key_operations
378
*/
379
as_status
380
aerospike_key_remove
(
381
aerospike
* as,
as_error
* err,
const
as_policy_remove
* policy,
const
as_key
* key
382
);
383
384
/**
385
* Asynchronously remove a record from the cluster.
386
*
387
* ~~~~~~~~~~{.c}
388
* void my_listener(as_error* err, void* udata, as_event_loop* event_loop)
389
* {
390
* if (err) {
391
* printf("Command failed: %d %s\n", err->code, err->message);
392
* return;
393
* }
394
* printf("Command succeeded\n");
395
* }
396
*
397
* as_key key;
398
* as_key_init(&key, "ns", "set", "key");
399
*
400
* as_status status = aerospike_key_remove(&as, &err, NULL, &key, my_listener, NULL, NULL, false);
401
* ~~~~~~~~~~
402
*
403
* @param as The aerospike instance to use for this operation.
404
* @param err The as_error to be populated if an error occurs.
405
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
406
* @param key The key of the record.
407
* @param listener User function to be called with command results.
408
* @param udata User data to be forwarded to user callback.
409
* @param event_loop Event loop assigned to run this command. If NULL, an event loop will be choosen by round-robin.
410
* @param pipeline Should responses be combined with other responses before sending back to client.
411
*
412
* @return AEROSPIKE_OK if async command succesfully queued. Otherwise an error.
413
*
414
* @ingroup key_operations
415
*/
416
as_status
417
aerospike_key_remove_async
(
418
aerospike
* as,
as_error
* err,
const
as_policy_remove
* policy,
const
as_key
* key,
419
as_async_write_listener
listener,
void
* udata,
as_event_loop
* event_loop,
bool
pipeline
420
);
421
422
/**
423
* Lookup a record by key, then perform specified operations.
424
*
425
* ~~~~~~~~~~{.c}
426
* as_key key;
427
* as_key_init(&key, "ns", "set", "key");
428
*
429
* as_operations ops;
430
* as_operations_inita(&ops,3);
431
* as_operations_add_incr(&ops, "bin1", 456);
432
* as_operations_add_append_str(&ops, "bin2", "def");
433
* as_operations_add_read(&ops, "bin1")
434
*
435
* as_record * rec = NULL;
436
*
437
* if (aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec) != AEROSPIKE_OK) {
438
* printf("error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
439
* }
440
* else {
441
* as_record_destroy(rec);
442
* }
443
* as_operations_destroy(&ops);
444
* ~~~~~~~~~~
445
*
446
* @param as The aerospike instance to use for this operation.
447
* @param err The as_error to be populated if an error occurs.
448
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
449
* @param key The key of the record.
450
* @param ops The operations to perform on the record.
451
* @param rec The record to be populated with the data from AS_OPERATOR_READ operations.
452
*
453
* @return AEROSPIKE_OK if successful. Otherwise an error.
454
*
455
* @ingroup key_operations
456
*/
457
as_status
458
aerospike_key_operate
(
459
aerospike
* as,
as_error
* err,
const
as_policy_operate
* policy,
const
as_key
* key,
460
const
as_operations
* ops,
as_record
** rec
461
);
462
463
/**
464
* Asynchronously lookup a record by key, then perform specified operations.
465
*
466
* ~~~~~~~~~~{.c}
467
* void my_listener(as_error* err, as_record* record, void* udata, as_event_loop* event_loop)
468
* {
469
* if (err) {
470
* printf("Command failed: %d %s\n", err->code, err->message);
471
* return;
472
* }
473
* // Process record bins
474
* // Do not call as_record_destroy() because the calling function will do that for you.
475
* }
476
*
477
* as_key key;
478
* as_key_init(&key, "ns", "set", "key");
479
*
480
* as_operations ops;
481
* as_operations_inita(&ops,3);
482
* as_operations_add_incr(&ops, "bin1", 456);
483
* as_operations_add_append_str(&ops, "bin2", "def");
484
* as_operations_add_read(&ops, "bin1")
485
*
486
* as_status status = aerospike_key_operate(&as, &err, NULL, &key, &ops, my_listener, NULL, NULL, false);
487
* as_operations_destroy(&ops);
488
* ~~~~~~~~~~
489
*
490
* @param as The aerospike instance to use for this operation.
491
* @param err The as_error to be populated if an error occurs.
492
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
493
* @param key The key of the record.
494
* @param ops The operations to perform on the record.
495
* @param listener User function to be called with command results.
496
* @param udata User data to be forwarded to user callback.
497
* @param event_loop Event loop assigned to run this command. If NULL, an event loop will be choosen by round-robin.
498
* @param pipeline Should responses be combined with other responses before sending back to client.
499
*
500
* @return AEROSPIKE_OK if async command succesfully queued. Otherwise an error.
501
*
502
* @ingroup key_operations
503
*/
504
as_status
505
aerospike_key_operate_async
(
506
aerospike
* as,
as_error
* err,
const
as_policy_operate
* policy,
const
as_key
* key,
const
as_operations
* ops,
507
as_async_record_listener
listener,
void
* udata,
as_event_loop
* event_loop,
bool
pipeline
508
);
509
510
/**
511
* Lookup a record by key, then apply the UDF.
512
*
513
* ~~~~~~~~~~{.c}
514
* as_key key;
515
* as_key_init(&key, "ns", "set", "key");
516
*
517
* as_arraylist args;
518
* as_arraylist_inita(&args, 2);
519
* as_arraylist_append_int64(&args, 1);
520
* as_arraylist_append_int64(&args, 2);
521
*
522
* as_val * res = NULL;
523
*
524
* if (aerospike_key_apply(&as, &err, NULL, &key, "math", "add", &args, &res) != AEROSPIKE_OK) {
525
* printf("error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
526
* }
527
* else {
528
* as_val_destroy(res);
529
* }
530
*
531
* as_arraylist_destroy(&args);
532
* ~~~~~~~~~~
533
*
534
*
535
* @param as The aerospike instance to use for this operation.
536
* @param err The as_error to be populated if an error occurs.
537
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
538
* @param key The key of the record.
539
* @param module The module containing the function to execute.
540
* @param function The function to execute.
541
* @param arglist The arguments for the function.
542
* @param result The return value from the function.
543
*
544
* @return AEROSPIKE_OK if successful. Otherwise an error.
545
*
546
* @ingroup key_operations
547
*/
548
as_status
aerospike_key_apply
(
549
aerospike
* as,
as_error
* err,
const
as_policy_apply
* policy,
550
const
as_key
* key,
551
const
char
* module,
const
char
*
function
,
as_list
* arglist,
552
as_val
** result
553
);
554
555
/**
556
* Asynchronously lookup a record by key, then apply the UDF.
557
*
558
* ~~~~~~~~~~{.c}
559
* void my_listener(as_error* err, as_val* val, void* udata, as_event_loop* event_loop)
560
* {
561
* if (err) {
562
* printf("Command failed: %d %s\n", err->code, err->message);
563
* return;
564
* }
565
* // Process value. The calling function will call as_val_destroy().
566
* // If the value needs to be preserved, bump up the reference count using as_val_reserve()
567
* // and call as_val_destroy() when done with the value.
568
* }
569
*
570
* as_key key;
571
* as_key_init(&key, "ns", "set", "key");
572
*
573
* as_arraylist args;
574
* as_arraylist_inita(&args, 2);
575
* as_arraylist_append_int64(&args, 1);
576
* as_arraylist_append_int64(&args, 2);
577
*
578
* as_status status = aerospike_key_apply(&as, &err, NULL, &key, "math", "add", &args, my_listener, NULL, NULL, false);
579
* as_arraylist_destroy(&args);
580
* ~~~~~~~~~~
581
*
582
* @param as The aerospike instance to use for this operation.
583
* @param err The as_error to be populated if an error occurs.
584
* @param policy The policy to use for this operation. If NULL, then the default policy will be used.
585
* @param key The key of the record.
586
* @param module The module containing the function to execute.
587
* @param function The function to execute.
588
* @param arglist The arguments for the function.
589
* @param listener User function to be called with command results.
590
* @param udata User data to be forwarded to user callback.
591
* @param event_loop Event loop assigned to run this command. If NULL, an event loop will be choosen by round-robin.
592
* @param pipeline Should responses be combined with other responses before sending back to client.
593
*
594
* @return AEROSPIKE_OK if async command succesfully queued. Otherwise an error.
595
*
596
* @ingroup key_operations
597
*/
598
as_status
599
aerospike_key_apply_async
(
600
aerospike
* as,
as_error
* err,
const
as_policy_apply
* policy,
const
as_key
* key,
601
const
char
* module,
const
char
*
function
,
as_list
* arglist,
602
as_async_value_listener
listener,
void
* udata,
as_event_loop
* event_loop,
bool
pipeline
603
);
604
605
/**
606
* Do the connected servers support the new floating point type.
607
* The cluster must already be connected (aerospike_connect()) prior to making this call.
608
*/
609
bool
610
aerospike_has_double
(
aerospike
* as);
611
612
/**
613
* Do the connected servers support geospatial data and queries.
614
* The cluster must already be connected (aerospike_connect()) prior to making this call.
615
*/
616
bool
617
aerospike_has_geo
(
aerospike
* as);
618
619
#ifdef __cplusplus
620
}
// end extern "C"
621
#endif