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-2015 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 query_operations Query Operations (3.0 only)
21  * @ingroup client_operations
22  *
23  * The Aerospike Query Operations provide the ability to query data in the
24  * Aerospike database. The queries can only be performed on secondary indexes,
25  * which have been created in the database. To scan all the records in the
26  * database, then you must use the @ref scan_operations.
27  *
28  * ## Usage
29  *
30  * Before you can execute a query, you first need to build a query using
31  * as_query. See as_query for details on building queries.
32  *
33  * Once you have a query defined, then you can execute the query :
34  *
35  * - aerospike_query_foreach() - Executes a query and invokes a callback
36  * function for each result returned.
37  *
38  * When aerospike_query_foreach() is executed, it will process the results
39  * and create records on the stack. Because the records are on the stack,
40  * they will only be available within the context of the callback function.
41  *
42  *
43  * ## Walk-through
44  *
45  * First, we define a query using as_query. The query will be for the "test"
46  * namespace and "demo" set. We will add a where predicate on "bin2", on which
47  * we have already created a secondary index.
48  *
49  * ~~~~~~~~~~{.c}
50  * as_query query;
51  * as_query_init(&query, "test", "demo");
52  *
53  * as_query_where_init(&query, 1);
54  * as_query_where(&query, "bin2", as_integer_equals(100));
55  * ~~~~~~~~~~
56  *
57  * Now that we have a query defined, we want to execute it using
58  * aerospike_query_foreach().
59  *
60  * ~~~~~~~~~~{.c}
61  * if ( aerospike_query_foreach(&as, &err, NULL, &query, callback, NULL) != AEROSPIKE_OK ) {
62  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
63  * }
64  * ~~~~~~~~~~
65  *
66  * The callback provided to the function above is implemented as:
67  *
68  * ~~~~~~~~~~{.c}
69  * bool callback(const as_val * val, void * udata) {
70  * as_record * rec = as_record_fromval(val);
71  * if ( !rec ) return false;
72  * fprintf("record contains %d bins", as_record_numbins(rec));
73  * return true;
74  * }
75  * ~~~~~~~~~~
76  *
77  * An as_query is simply a query definition, so it does not contain any state,
78  * allowing it to be reused for multiple query operations.
79  *
80  * When you are finished with the query, you should destroy the resources
81  * allocated to it:
82  *
83  * ~~~~~~~~~~{.c}
84  * as_query_destroy(&query);
85  * ~~~~~~~~~~
86  *
87  */
88 
89 #include <aerospike/aerospike.h>
90 #include <aerospike/as_error.h>
91 #include <aerospike/as_policy.h>
92 #include <aerospike/as_query.h>
93 #include <aerospike/as_status.h>
94 #include <aerospike/as_stream.h>
95 
96 #ifdef __cplusplus
97 extern "C" {
98 #endif
99 
100 /******************************************************************************
101  * TYPES
102  *****************************************************************************/
103 
104 /**
105  * This callback will be called for each value or record returned from a query.
106  * Multiple threads will likely be calling this callback in parallel. Therefore,
107  * your callback implementation should be thread safe.
108  *
109  * The aerospike_query_foreach() function accepts this callback.
110  *
111  * ~~~~~~~~~~{.c}
112  * bool my_callback(as_val * val, void * udata) {
113  * return true;
114  * }
115  * ~~~~~~~~~~
116  *
117  * @param val The value received from the query.
118  * @param udata User-data provided to the calling function.
119  *
120  * @return `true` to continue to the next value. Otherwise, iteration will end.
121  *
122  * @ingroup query_operations
123  */
124 typedef bool (* aerospike_query_foreach_callback)(const as_val * val, void * udata);
125 
126 /******************************************************************************
127  * FUNCTIONS
128  *****************************************************************************/
129 
130 /**
131  * Execute a query and call the callback function for each result item.
132  * Multiple threads will likely be calling the callback in parallel. Therefore,
133  * your callback implementation should be thread safe.
134  *
135  * ~~~~~~~~~~{.c}
136  * as_query query;
137  * as_query_init(&query, "test", "demo");
138  * as_query_select(&query, "bin1");
139  * as_query_where(&query, "bin2", as_integer_equals(100));
140  *
141  * if ( aerospike_query_foreach(&as, &err, NULL, &query, callback, NULL) != AEROSPIKE_OK ) {
142  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
143  * }
144  *
145  * as_query_destroy(&query);
146  * ~~~~~~~~~~
147  *
148  * @param as The aerospike instance to use for this operation.
149  * @param err The as_error to be populated if an error occurs.
150  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
151  * @param query The query to execute against the cluster.
152  * @param callback The callback function to call for each result value.
153  * @param udata User-data to be passed to the callback.
154  *
155  * @return AEROSPIKE_OK on success, otherwise an error.
156  *
157  * @ingroup query_operations
158  */
160  aerospike * as, as_error * err, const as_policy_query * policy,
161  const as_query * query,
162  aerospike_query_foreach_callback callback, void * udata
163  );
164 
165 #ifdef __cplusplus
166 } // end extern "C"
167 #endif