All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
aerospike_index.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 #ifdef __cplusplus
20 extern "C" {
21 #endif
22 
23 /**
24  * @defgroup index_operations Index Operations
25  * @ingroup client_operations
26  *
27  * The Index API provides the ability to create and remove secondary indexes.
28  *
29  * Aerospike currently supports indexing of strings and integers.
30  *
31  * ## String Indexes
32  *
33  * A string index allows for equality lookups. An equality lookup means that
34  * if you query for an indexed bin with value "abc", then only the records
35  * containing bins with "abc" will be returned.
36  *
37  * ## Integer Indexes
38  *
39  * An integer index allows for either equality or range lookups. An equality
40  * lookup means that if you query for an indexed bin with value 123, then only
41  * the records containing bins with the value 123 will be returned. A range
42  * lookup means that you can query bins within a range. So, if your range is
43  * (1...100), then all records containing the a value in that range will
44  * be returned.
45  */
46 
47 #include <aerospike/aerospike.h>
48 #include <aerospike/as_bin.h>
49 #include <aerospike/as_error.h>
50 #include <aerospike/as_key.h>
51 #include <aerospike/as_policy.h>
52 #include <aerospike/as_status.h>
53 
54 /******************************************************************************
55  * TYPES
56  *****************************************************************************/
57 #define AS_INDEX_POSITION_MAX_SZ 256
58 
60 
61 /**
62  * Index Type
63  *
64  * @ingroup index_operations
65  */
66 typedef enum as_index_type_s {
72 
73 /*
74  * Type of data which is going to indexed
75  */
76 typedef enum as_index_datatype_s {
80 
81 /**
82  * Index Task
83  *
84  * Task used to poll for long running create index completion.
85  *
86  * @ingroup index_operations
87  */
88 typedef struct as_index_task_s {
89  /**
90  * The aerospike instance to use for this operation.
91  */
93 
94  /**
95  * The namespace to be indexed.
96  */
98 
99  /**
100  * The name of the index.
101  */
102  char name[64];
103 
104  /**
105  * Has operation completed
106  */
107  bool done;
108 } as_index_task;
109 
110 
111 /******************************************************************************
112  * FUNCTIONS
113  *****************************************************************************/
114 
115 /**
116  * Create secondary index given collection type and data type.
117  *
118  * This asynchronous server call will return before the command is complete.
119  * The user can optionally wait for command completion by using a task instance.
120  *
121  * ~~~~~~~~~~{.c}
122  * as_index_task task;
123  * if ( aerospike_index_create_complex(&as, &err, &task, NULL, "test", "demo", "bin1",
124  * "idx_test_demo_bin1", AS_INDEX_TYPE_DEFAULT, AS_INDEX_NUMERIC) == AEROSPIKE_OK ) {
125  * aerospike_index_create_wait(&err, &task, 0);
126  * }
127 * ~~~~~~~~~~
128  *
129  * @param as The aerospike instance to use for this operation.
130  * @param err The as_error to be populated if an error occurs.
131  * @param task The optional task data used to poll for completion.
132  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
133  * @param ns The namespace to be indexed.
134  * @param set The set to be indexed.
135  * @param position The bin or complex position name to be indexed.
136  * @param name The name of the index.
137  * @param itype The type of index, default or complex type.
138  * @param dtype The data type of index, string or integer.
139  *
140  * @return AEROSPIKE_OK if successful or index already exists. Otherwise an error.
141  *
142  * @ingroup index_operations
143  */
145  aerospike * as, as_error * err, as_index_task * task, const as_policy_info * policy,
146  const as_namespace ns, const as_set set, const as_index_position position, const char * name,
147  as_index_type itype, as_index_datatype dtype);
148 
149 /**
150  * Create secondary index given data type.
151  *
152  * This asynchronous server call will return before the command is complete.
153  * The user can optionally wait for command completion by using a task instance.
154  *
155  * ~~~~~~~~~~{.c}
156  * as_index_task task;
157  * if ( aerospike_index_create(&as, &err, &task, NULL, "test", "demo", "bin1",
158  * "idx_test_demo_bin1", AS_INDEX_NUMERIC) == AEROSPIKE_OK ) {
159  * aerospike_index_create_wait(&err, &task, 0);
160  * }
161  * ~~~~~~~~~~
162  *
163  * @param as The aerospike instance to use for this operation.
164  * @param err The as_error to be populated if an error occurs.
165  * @param task The optional task data used to poll for completion.
166  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
167  * @param ns The namespace to be indexed.
168  * @param set The set to be indexed.
169  * @param bin The bin to be indexed.
170  * @param name The name of the index.
171  * @param dtype The data type of index, string or integer.
172  *
173  * @return AEROSPIKE_OK if successful or index already exists. Otherwise an error.
174  *
175  * @ingroup index_operations
176  */
178  aerospike * as, as_error * err, as_index_task * task, const as_policy_info * policy,
179  const as_namespace ns, const as_set set, const as_bin_name bin, const char * name,
180  as_index_datatype dtype)
181 {
182  return aerospike_index_create_complex(as, err, task, policy, ns, set, bin, name, AS_INDEX_TYPE_DEFAULT, dtype);
183 }
184 
185 /**
186  * Wait for asynchronous task to complete using given polling interval.
187  *
188  * @param err The as_error to be populated if an error occurs.
189  * @param task The task data used to poll for completion.
190  * @param interval_ms The polling interval in milliseconds. If zero, 1000 ms is used.
191  *
192  * @return AEROSPIKE_OK if successful. Otherwise an error.
193  *
194  * @ingroup index_operations
195  */
196 as_status aerospike_index_create_wait(as_error * err, as_index_task * task, uint32_t interval_ms);
197 
198 /**
199  * Removes (drops) a secondary index.
200  *
201  * ~~~~~~~~~~{.c}
202  * if ( aerospike_index_remove(&as, &err, NULL, "test", idx_test_demo_bin1") != AEROSPIKE_OK ) {
203  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
204  * }
205  * ~~~~~~~~~~
206  *
207  * @param as The aerospike instance to use for this operation.
208  * @param err The as_error to be populated if an error occurs.
209  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
210  * @param ns The namespace containing the index to be removed.
211  * @param name The name of the index to be removed.
212  *
213  * @return AEROSPIKE_OK if successful or index does not exist. Otherwise an error.
214  *
215  * @ingroup index_operations
216  */
218  aerospike * as, as_error * err, const as_policy_info * policy,
219  const as_namespace ns, const char * name);
220 
221 /******************************************************************************
222  * DEPRECATED FUNCTIONS
223  *****************************************************************************/
224 
225 /**
226  * Create a new secondary index on an integer bin.
227  *
228  * @deprecated Use aerospike_index_create() instead.
229  *
230  * @ingroup index_operations
231  */
233  aerospike * as, as_error * err, const as_policy_info * policy,
234  const as_namespace ns, const as_set set, const as_bin_name bin, const char * name)
235 {
236  return aerospike_index_create_complex(as, err, 0, policy, ns, set, bin, name, AS_INDEX_TYPE_DEFAULT, AS_INDEX_NUMERIC);
237 }
238 
239 /**
240  * Create a new secondary index on a string bin.
241  *
242  * @deprecated Use aerospike_index_create() instead.
243  *
244  * @ingroup index_operations
245  */
247  aerospike * as, as_error * err, const as_policy_info * policy,
248  const as_namespace ns, const as_set set, const as_bin_name bin, const char * name)
249 {
250  return aerospike_index_create_complex(as, err, 0, policy, ns, set, bin, name, AS_INDEX_TYPE_DEFAULT, AS_INDEX_STRING);
251 }
252 
253 #ifdef __cplusplus
254 } // end extern "C"
255 #endif
char as_index_position[AS_INDEX_POSITION_MAX_SZ]
as_status aerospike_index_create_wait(as_error *err, as_index_task *task, uint32_t interval_ms)
as_namespace ns
Definition: as_scan.h:345
as_status
Definition: as_status.h:30
as_status aerospike_index_create_complex(aerospike *as, as_error *err, as_index_task *task, const as_policy_info *policy, const as_namespace ns, const as_set set, const as_index_position position, const char *name, as_index_type itype, as_index_datatype dtype)
as_status aerospike_index_remove(aerospike *as, as_error *err, const as_policy_info *policy, const as_namespace ns, const char *name)
char as_namespace[AS_NAMESPACE_MAX_SIZE]
Definition: as_key.h:66
static as_status aerospike_index_create(aerospike *as, as_error *err, as_index_task *task, const as_policy_info *policy, const as_namespace ns, const as_set set, const as_bin_name bin, const char *name, as_index_datatype dtype)
static as_status aerospike_index_integer_create(aerospike *as, as_error *err, const as_policy_info *policy, const as_namespace ns, const as_set set, const as_bin_name bin, const char *name)
#define AS_INDEX_POSITION_MAX_SZ
static as_status aerospike_index_string_create(aerospike *as, as_error *err, const as_policy_info *policy, const as_namespace ns, const as_set set, const as_bin_name bin, const char *name)
as_index_type
as_index_datatype
aerospike * as
char as_bin_name[AS_BIN_NAME_MAX_SIZE]
Definition: as_bin.h:51
as_namespace ns
char as_set[AS_SET_MAX_SIZE]
Definition: as_key.h:73