All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
aerospike_query.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 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. Also, we will limit
48  * the results to 100 records.
49  *
50  * ~~~~~~~~~~{.c}
51  * as_query query;
52  * as_query_init(&query, "test", "demo");
53  * as_query_limit(&query, 100);
54  *
55  * as_query_where_init(&query, 1);
56  * as_query_where(&query, "bin2", integer_equals(100));
57  * ~~~~~~~~~~
58  *
59  * Now that we have a query defined, we want to execute it using
60  * aerospike_query_foreach().
61  *
62  * ~~~~~~~~~~{.c}
63  * if ( aerospike_query_foreach(&as, &err, NULL, &query, callback, NULL) != AEROSPIKE_OK ) {
64  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
65  * }
66  * ~~~~~~~~~~
67  *
68  * The callback provided to the function above is implemented as:
69  *
70  * ~~~~~~~~~~{.c}
71  * bool callback(const as_val * val, void * udata) {
72  * as_record * rec = as_record_fromval(val);
73  * if ( !rec ) return false;
74  * fprintf("record contains %d bins", as_record_numbins(rec));
75  * return true;
76  * }
77  * ~~~~~~~~~~
78  *
79  * An as_query is simply a query definition, so it does not contain any state,
80  * allowing it to be reused for multiple query operations.
81  *
82  * When you are finished with the query, you should destroy the resources
83  * allocated to it:
84  *
85  * ~~~~~~~~~~{.c}
86  * as_query_destroy(&query);
87  * ~~~~~~~~~~
88  *
89  */
90 
91 #include <aerospike/aerospike.h>
92 #include <aerospike/as_error.h>
93 #include <aerospike/as_policy.h>
94 #include <aerospike/as_query.h>
95 #include <aerospike/as_status.h>
96 #include <aerospike/as_stream.h>
97 
98 /******************************************************************************
99  * TYPES
100  *****************************************************************************/
101 
102 /**
103  * This callback will be called for each value or record returned from
104  * a query.
105  *
106  * The aerospike_query_foreach() function accepts this callback.
107  *
108  * ~~~~~~~~~~{.c}
109  * bool my_callback(as_val * val, void * udata) {
110  * return true;
111  * }
112  * ~~~~~~~~~~
113  *
114  * @param val The value received from the query.
115  * @param udata User-data provided to the calling function.
116  *
117  * @return `true` to continue to the next value. Otherwise, iteration will end.
118  *
119  * @ingroup query_operations
120  */
121 typedef bool (* aerospike_query_foreach_callback)(const as_val * val, void * udata);
122 
123 /******************************************************************************
124  * FUNCTIONS
125  *****************************************************************************/
126 
127 /**
128  * Execute a query and call the callback function for each result item.
129  *
130  * ~~~~~~~~~~{.c}
131  * as_query query;
132  * as_query_init(&query, "test", "demo");
133  * as_query_select(&query, "bin1");
134  * as_query_where(&query, "bin2", integer_equals(100));
135  *
136  * if ( aerospike_query_foreach(&as, &err, NULL, &query, callback, NULL) != AEROSPIKE_OK ) {
137  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
138  * }
139  *
140  * as_query_destroy(&query);
141  * ~~~~~~~~~~
142  *
143  * @param as The aerospike instance to use for this operation.
144  * @param err The as_error to be populated if an error occurs.
145  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
146  * @param query The query to execute against the cluster.
147  * @param callback The callback function to call for each result value.
148  * @param udata User-data to be passed to the callback.
149  *
150  * @return AEROSPIKE_OK on success, otherwise an error.
151  *
152  * @ingroup query_operations
153  */
155  aerospike * as, as_error * err, const as_policy_query * policy,
156  const as_query * query,
157  aerospike_query_foreach_callback callback, void * udata
158  );
as_status
Definition: as_status.h:26
bool(* aerospike_query_foreach_callback)(const as_val *val, void *udata)
Definition: as_val.h:51
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)