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-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
*/
159
as_status
aerospike_query_foreach
(
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
as_error
Definition:
as_error.h:96
as_status
as_status
Definition:
as_status.h:30
as_val
Definition:
as_val.h:55
as_policy.h
as_status.h
as_policy_query
Definition:
as_policy.h:536
as_stream.h
aerospike_query_foreach_callback
bool(* aerospike_query_foreach_callback)(const as_val *val, void *udata)
Definition:
aerospike_query.h:124
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:162
as_query.h
aerospike.h
as_query
Definition:
as_query.h:466