Main Page
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Friends
Macros
Groups
Pages
aerospike
aerospike_query.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 query_operations Query Operations (3.0 only)
25
* @ingroup client_operations
26
*
27
* The Aerospike Query Operations provide the ability to query data in the
28
* Aerospike database. The queries can only be performed on secondary indexes,
29
* which have been created in the database. To scan all the records in the
30
* database, then you must use the @ref scan_operations.
31
*
32
* ## Usage
33
*
34
* Before you can execute a query, you first need to build a query using
35
* as_query. See as_query for details on building queries.
36
*
37
* Once you have a query defined, then you can execute the query
38
* using either:
39
*
40
* - aerospike_query_foreach() - Executes a query and invokes a callback
41
* function for each result returned.
42
* - aerospike_query_stream() - Executes a query and writes the results
43
* to the stream provided.
44
*
45
* The two operations are very similar in that they provide the ability to read
46
* the records returned from a query. However, they differ in how they
47
* manage resources.
48
*
49
* When aerospike_query_foreach() is executed, it will process the results
50
* and create records on the stack. Because the records are on the stack,
51
* they will only be available within the context of the callback function.
52
* If you want the record available outside the callback, then you must use
53
* aerospike_query_stream().
54
*
55
* When aerospike_query_stream() is executed, it will process the results
56
* and create records on the heap. These records are sent to the stream's
57
* write callback. Because the records are on the heap, the stream is able
58
* to pass the record outside the scope of the write callback. This form of
59
* processing is more expensive in terms CPU, but provides added flexibility.
60
*
61
*
62
* ## Walk-through
63
*
64
* First, we define a query using as_query. The query will be for the "test"
65
* namespace and "demo" set. We will add a where predicate on "bin2", on which
66
* we have already created a secondary index. Also, we will limit
67
* the results to 100 records.
68
*
69
* ~~~~~~~~~~{.c}
70
* as_query query;
71
* as_query_init(&query, "test", "demo");
72
* as_query_limit(&query, 100);
73
*
74
* as_query_where_init(&query, 1);
75
* as_query_where(&query, "bin2", integer_equals(100));
76
* ~~~~~~~~~~
77
*
78
* Now that we have a query defined, we want to execute it using
79
* aerospike_query_foreach().
80
*
81
* ~~~~~~~~~~{.c}
82
* if ( aerospike_query_foreach(&as, &err, NULL, &query, callback, NULL) != AEROSPIKE_OK ) {
83
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
84
* }
85
* ~~~~~~~~~~
86
*
87
* The callback provided to the function above is implemented as:
88
*
89
* ~~~~~~~~~~{.c}
90
* bool callback(const as_val * val, void * udata) {
91
* as_record * rec = as_record_fromval(val);
92
* if ( !rec ) return false;
93
* fprintf("record contains %d bins", as_record_numbins(rec));
94
* return true;
95
* }
96
* ~~~~~~~~~~
97
*
98
* An as_query is simply a query definition, so it does not contain any state,
99
* allowing it to be reused for multiple query operations.
100
*
101
* When you are finished with the query, you should destroy the resources
102
* allocated to it:
103
*
104
* ~~~~~~~~~~{.c}
105
* as_query_destroy(&query);
106
* ~~~~~~~~~~
107
*
108
*/
109
110
#pragma once
111
112
#include <
aerospike/aerospike.h
>
113
#include <
aerospike/as_error.h
>
114
#include <
aerospike/as_policy.h
>
115
#include <
aerospike/as_query.h
>
116
#include <
aerospike/as_status.h
>
117
#include <
aerospike/as_stream.h
>
118
119
/******************************************************************************
120
* TYPES
121
*****************************************************************************/
122
123
/**
124
* This callback will be called for each value or record returned from
125
* a query.
126
*
127
* The aerospike_query_foreach() function accepts this callback.
128
*
129
* ~~~~~~~~~~{.c}
130
* bool my_callback(as_val * val, void * udata) {
131
* return true;
132
* }
133
* ~~~~~~~~~~
134
*
135
* @param val The value received from the query.
136
* @param udata User-data provided to the calling function.
137
*
138
* @return `true` to continue to the next value. Otherwise, iteration will end.
139
*
140
* @ingroup query_operations
141
*/
142
typedef
bool (*
aerospike_query_foreach_callback
)(
const
as_val
* val,
void
* udata);
143
144
/******************************************************************************
145
* FUNCTIONS
146
*****************************************************************************/
147
148
/**
149
* Execute a query and call the callback function for each result item.
150
*
151
* ~~~~~~~~~~{.c}
152
* as_query query;
153
* as_query_init(&query, "test", "demo");
154
* as_query_select(&query, "bin1");
155
* as_query_where(&query, "bin2", integer_equals(100));
156
*
157
* if ( aerospike_query_foreach(&as, &err, NULL, &query, callback, NULL) != AEROSPIKE_OK ) {
158
* fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
159
* }
160
*
161
* as_query_destroy(&query);
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 query The query to execute against the cluster.
168
* @param callback The callback function to call for each result value.
169
* @param udata User-data to be passed to the callback.
170
*
171
* @return AEROSPIKE_OK on success, otherwise an error.
172
*
173
* @ingroup query_operations
174
*/
175
as_status
aerospike_query_foreach
(
176
aerospike
* as,
as_error
* err,
const
as_policy_query
* policy,
177
const
as_query
* query,
178
aerospike_query_foreach_callback
callback,
void
* udata
179
);
as_error
Definition:
as_error.h:98
as_status
as_status
Definition:
as_status.h:32
as_val
Definition:
as_val.h:56
as_policy.h
as_status.h
as_policy_query
Definition:
as_policy.h:440
as_stream.h
aerospike_query_foreach_callback
bool(* aerospike_query_foreach_callback)(const as_val *val, void *udata)
Definition:
aerospike_query.h:142
aerospike_query_foreach
as_status aerospike_query_foreach(aerospike *as, as_error *err, const as_policy_query *policy, const as_query *query, aerospike_query_foreach_callback callback, void *udata)
as_error.h
aerospike
Definition:
aerospike.h:164
as_query.h
aerospike.h
as_query
Definition:
as_query.h:430