All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
aerospike_index.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 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 /******************************************************************************
51  * TYPES
52  *****************************************************************************/
53 
54 /**
55  * Index Type
56  *
57  * @ingroup index_operations
58  */
59 typedef enum as_index_type_e {
60  /**
61  * Index on integer bin.
62  */
64 
65  /**
66  * Index on string bin.
67  */
70 
71 /**
72  * Index Task
73  *
74  * Task used to poll for long running create index completion.
75  *
76  * @ingroup index_operations
77  */
78 typedef struct as_index_task_s {
79  /**
80  * The aerospike instance to use for this operation.
81  */
83 
84  /**
85  * The namespace to be indexed.
86  */
88 
89  /**
90  * The name of the index.
91  */
92  char name[64];
93 
94  /**
95  * Has operation completed
96  */
97  bool done;
99 
100 /******************************************************************************
101  * FUNCTIONS
102  *****************************************************************************/
103 
104 /**
105  * Create secondary index.
106  *
107  * This asynchronous server call will return before the command is complete.
108  * The user can optionally wait for command completion by using a task instance.
109  *
110  * ~~~~~~~~~~{.c}
111  * as_index_task task;
112  * if ( aerospike_index_create(&as, &err, &task, NULL, "test", "demo", "bin1", "idx_test_demo_bin1") == AEROSPIKE_OK ) {
113  * aerospike_index_create_wait(&err, &task, 0);
114  * }
115  * ~~~~~~~~~~
116  *
117  * @param as The aerospike instance to use for this operation.
118  * @param err The as_error to be populated if an error occurs.
119  * @param task The optional task data used to poll for completion.
120  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
121  * @param ns The namespace to be indexed.
122  * @param set The set to be indexed.
123  * @param bin The bin to be indexed.
124  * @param name The name of the index.
125  *
126  * @return AEROSPIKE_OK if successful or index already exists. Otherwise an error.
127  *
128  * @ingroup index_operations
129  */
131  aerospike * as, as_error * err, as_index_task * task, const as_policy_info * policy,
132  const as_namespace ns, const as_set set, const as_bin_name bin, const char * name, as_index_type type);
133 
134 /**
135  * Wait for asynchronous task to complete using given polling interval.
136  *
137  * @param err The as_error to be populated if an error occurs.
138  * @param task The task data used to poll for completion.
139  * @param interval_ms The polling interval in milliseconds. If zero, 1000 ms is used.
140  *
141  * @return AEROSPIKE_OK if successful. Otherwise an error.
142  *
143  * @ingroup index_operations
144  */
145 as_status aerospike_index_create_wait(as_error * err, as_index_task * task, uint32_t interval_ms);
146 
147 /**
148  * Removes (drops) a secondary index.
149  *
150  * ~~~~~~~~~~{.c}
151  * if ( aerospike_index_remove(&as, &err, NULL, "test", idx_test_demo_bin1") != AEROSPIKE_OK ) {
152  * fprintf(stderr, "error(%d) %s at [%s:%d]", err.code, err.message, err.file, err.line);
153  * }
154  * ~~~~~~~~~~
155  *
156  * @param as The aerospike instance to use for this operation.
157  * @param err The as_error to be populated if an error occurs.
158  * @param policy The policy to use for this operation. If NULL, then the default policy will be used.
159  * @param ns The namespace containing the index to be removed.
160  * @param name The name of the index to be removed.
161  *
162  * @return AEROSPIKE_OK if successful or index does not exist. Otherwise an error.
163  *
164  * @ingroup index_operations
165  */
167  aerospike * as, as_error * err, const as_policy_info * policy,
168  const as_namespace ns, const char * name);
169 
170 /******************************************************************************
171  * DEPRECATED FUNCTIONS
172  *****************************************************************************/
173 
174 /**
175  * Create a new secondary index on an integer bin.
176  *
177  * @deprecated Use aerospike_index_create() instead.
178  *
179  * @ingroup index_operations
180  */
182  aerospike * as, as_error * err, const as_policy_info * policy,
183  const as_namespace ns, const as_set set, const as_bin_name bin, const char * name)
184 {
185  return aerospike_index_create(as, err, 0, policy, ns, set, bin, name, AS_INDEX_NUMERIC);
186 }
187 
188 /**
189  * Create a new secondary index on a string bin.
190  *
191  * @deprecated Use aerospike_index_create() instead.
192  *
193  * @ingroup index_operations
194  */
196  aerospike * as, as_error * err, const as_policy_info * policy,
197  const as_namespace ns, const as_set set, const as_bin_name bin, const char * name)
198 {
199  return aerospike_index_create(as, err, 0, policy, ns, set, bin, name, AS_INDEX_STRING);
200 }
as_status aerospike_index_create_wait(as_error *err, as_index_task *task, uint32_t interval_ms)
as_namespace ns
Definition: as_scan.h:328
as_status
Definition: as_status.h:26
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:60
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)
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
aerospike * as
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_type type)
char as_bin_name[AS_BIN_NAME_MAX_SIZE]
Definition: as_bin.h:47
as_namespace ns
char as_set[AS_SET_MAX_SIZE]
Definition: as_key.h:67