All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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  */
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_status
Definition: as_status.h:32
Definition: as_val.h:56
bool(* aerospike_query_foreach_callback)(const as_val *val, void *udata)
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)