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