1 /* -*- Mode: C; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */ 2 /* 3 * Copyright 2018 Couchbase, Inc. 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * 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, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 **/ 17 18 #ifndef LCB_ANALYTICS_API_H 19 #define LCB_ANALYTICS_API_H 20 #include <libcouchbase/couchbase.h> 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif 25 26 /** 27 * @addtogroup lcb-n1ql-api 28 * @{ 29 */ 30 typedef struct lcb_RESPANALYTICS lcb_RESPANALYTICS; 31 32 typedef struct lcb_CMDANALYTICS_st lcb_CMDANALYTICS; 33 typedef struct lcb_ANALYTICSREQ *lcb_ANALYTICSHANDLE; 34 35 typedef void (*lcb_ANALYTICSCALLBACK)(lcb_t, int, const lcb_RESPANALYTICS *); 36 37 LIBCOUCHBASE_API 38 lcb_CMDANALYTICS *lcb_analytics_new(void); 39 40 LIBCOUCHBASE_API 41 void lcb_analytics_reset(lcb_CMDANALYTICS *cmd); 42 43 LIBCOUCHBASE_API 44 void lcb_analytics_free(lcb_CMDANALYTICS *cmd); 45 46 LIBCOUCHBASE_API 47 lcb_error_t lcb_analytics_setcallback(lcb_CMDANALYTICS *cmd, lcb_ANALYTICSCALLBACK callback); 48 49 LIBCOUCHBASE_API 50 lcb_error_t lcb_analytics_setquery(lcb_CMDANALYTICS *cmd, const char *query, size_t nquery); 51 #define lcb_analytics_setqueryz(cmd, qstr) lcb_analytics_setquery(cmd, qstr, -1) 52 53 LIBCOUCHBASE_API 54 lcb_error_t lcb_analytics_setstatement(lcb_CMDANALYTICS *cmd, const char *statement, size_t nstatement); 55 #define lcb_analytics_setstatementz(cmd, sstr) lcb_analytics_setstatement(cmd, sstr, -1) 56 57 LIBCOUCHBASE_API 58 lcb_error_t lcb_analytics_namedparam(lcb_CMDANALYTICS *cmd, const char *name, size_t nname, const char *value, 59 size_t nvalue); 60 #define lcb_analytics_namedparamz(cmd, name, value) lcb_analytics_namedparam(cmd, name, -1, value, -1) 61 62 LIBCOUCHBASE_API 63 lcb_error_t lcb_analytics_posparam(lcb_CMDANALYTICS *cmd, const char *value, size_t nvalue); 64 65 LIBCOUCHBASE_API 66 lcb_error_t lcb_analytics_setopt(lcb_CMDANALYTICS *cmd, const char *name, size_t nname, const char *value, 67 size_t nvalue); 68 #define lcb_analytics_setoptz(cmd, key, value) lcb_analytics_setopt(cmd, key, -1, value, -1) 69 70 LIBCOUCHBASE_API 71 lcb_error_t lcb_analytics_setdeferred(lcb_CMDANALYTICS *cmd, int deferred); 72 73 typedef enum { 74 LCB_ANALYTICSINGEST_NONE = 0, 75 LCB_ANALYTICSINGEST_UPSERT, 76 LCB_ANALYTICSINGEST_INSERT, 77 LCB_ANALYTICSINGEST_REPLACE, 78 LCB_ANALYTICSINGEST__METHOD_MAX 79 } lcb_ANALYTICSINGESTMETHOD; 80 81 LIBCOUCHBASE_API 82 lcb_error_t lcb_analytics_ingest_setmethod(lcb_CMDANALYTICS *cmd, lcb_ANALYTICSINGESTMETHOD method); 83 84 LIBCOUCHBASE_API 85 lcb_error_t lcb_analytics_ingest_setexptime(lcb_CMDANALYTICS *cmd, lcb_U32 exptime); 86 87 LIBCOUCHBASE_API 88 lcb_error_t lcb_analytics_ingest_ignoreingesterror(lcb_CMDANALYTICS *cmd, int ignore); 89 90 typedef enum { 91 LCB_ANALYTICSINGEST_OK = 0, 92 LCB_ANALYTICSINGEST_IGNORE, 93 LCB_ANALYTICSINGEST__STATUS_MAX 94 } lcb_ANALYTICSINGESTSTATUS; 95 96 typedef struct { 97 /* input */ 98 lcb_ANALYTICSINGESTMETHOD method; 99 const char *row; 100 size_t nrow; 101 102 /* output */ 103 char *id; 104 size_t nid; 105 void (*id_free)(void *); 106 } lcb_ANALYTICSINGESTIDGENERATORPARAM; 107 108 typedef lcb_ANALYTICSINGESTSTATUS (*lcb_ANALYTICSINGESTIDGENERATOR)(lcb_t, const void *, lcb_ANALYTICSINGESTIDGENERATORPARAM *); 109 110 LIBCOUCHBASE_API 111 lcb_error_t lcb_analytics_ingest_setidgenerator(lcb_CMDANALYTICS *cmd, lcb_ANALYTICSINGESTIDGENERATOR generator); 112 113 typedef struct { 114 /* input */ 115 lcb_ANALYTICSINGESTMETHOD method; 116 const char *row; 117 size_t nrow; 118 119 /* output, NULL for passthrough */ 120 char *out; 121 size_t nout; 122 void (*out_free)(void *); 123 } lcb_ANALYTICSINGESTDATACONVERTERPARAM; 124 125 typedef lcb_ANALYTICSINGESTSTATUS (*lcb_ANALYTICSINGESTDATACONVERTER)(lcb_t, const void *, lcb_ANALYTICSINGESTDATACONVERTERPARAM *); 126 127 LIBCOUCHBASE_API 128 lcb_error_t lcb_analytics_ingest_setdataconverter(lcb_CMDANALYTICS *cmd, lcb_ANALYTICSINGESTDATACONVERTER converter); 129 130 /** 131 * Response for a Analytics query. This is delivered in the @ref lcb_ANALYTICSCALLBACK 132 * callback function for each result row received. The callback is also called 133 * one last time when all 134 */ 135 struct lcb_RESPANALYTICS { 136 #ifndef __LCB_DOXYGEN__ 137 LCB_RESP_BASE 138 #else 139 lcb_U16 rflags; /**< Flags for response structure */ 140 #endif 141 142 /**Current result row. If #rflags has the ::LCB_RESP_F_FINAL bit set, then 143 * this field does not contain the actual row, but the remainder of the 144 * data not included with the resultset; e.g. the JSON surrounding 145 * the "results" field with any errors or metadata for the response. 146 */ 147 const char *row; 148 /** Length of the row */ 149 size_t nrow; 150 /** Raw HTTP response, if applicable */ 151 const lcb_RESPHTTP *htresp; 152 }; 153 154 /** 155 * @volatile 156 * 157 * Execute a Analytics query. 158 * 159 * This function will send the query to a query server in the cluster 160 * and will invoke the callback (lcb_CMDANALYTICS::callback) for each result returned. 161 * 162 * @param instance The instance 163 * @param cookie Pointer to application data 164 * @param cmd the command 165 * @return Scheduling success or failure. 166 */ 167 LIBCOUCHBASE_API 168 lcb_error_t lcb_analytics_query(lcb_t instance, const void *cookie, lcb_CMDANALYTICS *cmd); 169 170 typedef struct lcb_ANALYTICSDEFERREDHANDLE_st lcb_ANALYTICSDEFERREDHANDLE; 171 172 LIBCOUCHBASE_API 173 lcb_ANALYTICSDEFERREDHANDLE *lcb_analytics_defhnd_extract(const lcb_RESPANALYTICS *response); 174 175 LIBCOUCHBASE_API 176 void lcb_analytics_defhnd_free(lcb_ANALYTICSDEFERREDHANDLE *handle); 177 178 LIBCOUCHBASE_API 179 const char *lcb_analytics_defhnd_status(lcb_ANALYTICSDEFERREDHANDLE *handle); 180 181 LIBCOUCHBASE_API 182 lcb_error_t lcb_analytics_defhnd_setcallback(lcb_ANALYTICSDEFERREDHANDLE *handle, lcb_ANALYTICSCALLBACK callback); 183 184 LIBCOUCHBASE_API 185 lcb_error_t lcb_analytics_defhnd_poll(lcb_t instance, const void *cookie, lcb_ANALYTICSDEFERREDHANDLE *handle); 186 /** 187 * Cancels an in-progress request. This will ensure that further callbacks 188 * for the given request are not delivered. 189 * 190 * @param instance the instance 191 * @param handle the handle for the request. This is obtained during the 192 * request as an 'out' parameter (see lcb_CMDANALYTICS::handle) 193 * 194 * To obtain the `handle` parameter, do something like this: 195 * 196 * @code{.c} 197 * lcb_CMDANALYTICS *cmd; 198 * // (Initialize command...) 199 * lcb_n1ql_query(instance, cookie, &cmd); 200 * lcb_ANALYTICSHANDLE handle = lcb_analytics_gethandle(cmd); 201 * lcb_analytics_free(cmd); 202 * @endcode. 203 * 204 * If the lcb_analytics_query() function returns `LCB_SUCCESS` then the `handle` 205 * above is populated with the opaque handle. You can then use this handle 206 * to cancel the query at a later point, such as within the callback. 207 * 208 * @code{.c} 209 * lcb_analytics_cancel(instance, handle); 210 * @endcode 211 */ 212 LIBCOUCHBASE_API 213 void lcb_analytics_cancel(lcb_t instance, lcb_ANALYTICSHANDLE handle); 214 215 /**@}*/ 216 217 /**@}*/ 218 219 /** 220 * @ingroup lcb-public-api 221 * @addtogroup lcb-tracing-api 222 * @{ 223 */ 224 #ifdef LCB_TRACING 225 226 /** 227 * Associate parent tracing span with the Analytics request. 228 * 229 * @param instance the instance 230 * @param handle Analytics request handle 231 * @param span parent span 232 * 233 * @par Attach parent tracing span to request object. 234 * @code{.c} 235 * lcb_CMDANALYTICS *cmd = lcb_analytics_new(); 236 * // initialize Analytics command... 237 * 238 * lcb_analytics_setparentspan(instance, handle, span); 239 * 240 * lcb_error_t err = lcb_analytics_query(instance, cookie, cmd); 241 * @endcode 242 * 243 * @committed 244 */ 245 LIBCOUCHBASE_API 246 void lcb_analytics_setparentspan(lcb_CMDANALYTICS *cmd, lcbtrace_SPAN *span); 247 248 #endif 249 /** 250 * @} (Group: Tracing) 251 */ 252 #ifdef __cplusplus 253 } 254 #endif 255 #endif 256