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.
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", 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 /******************************************************************************
97  * TYPES
98  *****************************************************************************/
99 
100 /**
101  * This callback will be called for each value or record returned from
102  * a query.
103  *
104  * The aerospike_query_foreach() function accepts this callback.
105  *
106  * ~~~~~~~~~~{.c}
107  * bool my_callback(as_val * val, void * udata) {
108  * return true;
109  * }
110  * ~~~~~~~~~~
111  *
112  * @param val The value received from the query.
113  * @param udata User-data provided to the calling function.
114  *
115  * @return `true` to continue to the next value. Otherwise, iteration will end.
116  *
117  * @ingroup query_operations
118  */
119 typedef bool (* aerospike_query_foreach_callback)(const as_val * val, void * udata);
120 
121 /******************************************************************************
122  * FUNCTIONS
123  *****************************************************************************/
124 
125 /**
126  * Execute a query and call the callback function for each result item.
127  *
128  * ~~~~~~~~~~{.c}
129  * as_query query;
130  * as_query_init(&query, "test", "demo");
131  * as_query_select(&query, "bin1");
132  * as_query_where(&query, "bin2", integer_equals(100));
133  *
134  * if ( aerospike_query_foreach(&as, &err, NULL, &query, callback, NULL) != AEROSPIKE_OK ) {
135  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
136  * }
137  *
138  * as_query_destroy(&query);
139  * ~~~~~~~~~~
140  *
141  * @param as The aerospike instance to use for this operation.
142  * @param err The as_error to be populated if an error occurs.
143  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
144  * @param query The query to execute against the cluster.
145  * @param callback The callback function to call for each result value.
146  * @param udata User-data to be passed to the callback.
147  *
148  * @return AEROSPIKE_OK on success, otherwise an error.
149  *
150  * @ingroup query_operations
151  */
153  aerospike * as, as_error * err, const as_policy_query * policy,
154  const as_query * query,
155  aerospike_query_foreach_callback callback, void * udata
156  );
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)