1
0
Fork 0
arangodb/arangod/VocBase/index.h

657 lines
27 KiB
C

////////////////////////////////////////////////////////////////////////////////
/// @brief index
///
/// @file
///
/// DISCLAIMER
///
/// Copyright 2004-2013 triAGENS GmbH, Cologne, Germany
///
/// Licensed under the Apache License, Version 2.0 (the "License");
/// you may not use this file except in compliance with the License.
/// You may obtain a copy of the License at
///
/// http://www.apache.org/licenses/LICENSE-2.0
///
/// Unless required by applicable law or agreed to in writing, software
/// distributed under the License is distributed on an "AS IS" BASIS,
/// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
/// See the License for the specific language governing permissions and
/// limitations under the License.
///
/// Copyright holder is triAGENS GmbH, Cologne, Germany
///
/// @author Dr. Frank Celler
/// @author Copyright 2011-2013, triAGENS GmbH, Cologne, Germany
////////////////////////////////////////////////////////////////////////////////
#ifndef TRIAGENS_VOC_BASE_INDEX_H
#define TRIAGENS_VOC_BASE_INDEX_H 1
#include "VocBase/vocbase.h"
#include "BasicsC/associative-multi.h"
#include "BasicsC/json.h"
#include "BasicsC/linked-list.h"
#include "BitIndexes/bitarrayIndex.h"
#include "FulltextIndex/fulltext-index.h"
#include "GeoIndex/GeoIndex.h"
#include "IndexIterators/index-iterator.h"
#include "IndexOperators/index-operator.h"
#include "PriorityQueue/pqueueindex.h"
#include "ShapedJson/shaped-json.h"
#include "SkipLists/skiplistIndex.h"
#include "SkipListsEx/skiplistExIndex.h"
#include "VocBase/voc-types.h"
#ifdef __cplusplus
extern "C" {
#endif
// -----------------------------------------------------------------------------
// --SECTION-- forward declarations
// -----------------------------------------------------------------------------
struct TRI_collection_s;
struct TRI_doc_mptr_s;
struct TRI_shaped_json_s;
struct TRI_document_collection_s;
struct TRI_transaction_collection_s;
// -----------------------------------------------------------------------------
// --SECTION-- public types
// -----------------------------------------------------------------------------
////////////////////////////////////////////////////////////////////////////////
/// @addtogroup VocBase
/// @{
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// @brief index type
////////////////////////////////////////////////////////////////////////////////
typedef enum {
TRI_IDX_TYPE_PRIMARY_INDEX,
TRI_IDX_TYPE_GEO1_INDEX,
TRI_IDX_TYPE_GEO2_INDEX,
TRI_IDX_TYPE_HASH_INDEX,
TRI_IDX_TYPE_EDGE_INDEX,
TRI_IDX_TYPE_FULLTEXT_INDEX,
TRI_IDX_TYPE_PRIORITY_QUEUE_INDEX,
TRI_IDX_TYPE_SKIPLIST_INDEX,
#ifdef TRI_SKIPLIST_EX
TRI_IDX_TYPE_SKIPLIST_EX_INDEX,
#endif
TRI_IDX_TYPE_BITARRAY_INDEX,
TRI_IDX_TYPE_CAP_CONSTRAINT
}
TRI_idx_type_e;
////////////////////////////////////////////////////////////////////////////////
/// @brief geo index variants
////////////////////////////////////////////////////////////////////////////////
typedef enum {
INDEX_GEO_NONE = 0,
INDEX_GEO_INDIVIDUAL_LAT_LON,
INDEX_GEO_COMBINED_LAT_LON,
INDEX_GEO_COMBINED_LON_LAT
}
TRI_index_geo_variant_e;
////////////////////////////////////////////////////////////////////////////////
/// @brief index base class
////////////////////////////////////////////////////////////////////////////////
typedef struct TRI_index_s {
TRI_idx_iid_t _iid;
TRI_idx_type_e _type;
struct TRI_primary_collection_s* _collection;
TRI_vector_string_t _fields;
bool _unique;
bool _ignoreNull;
bool _needsFullCoverage;
const char* (*typeName) (struct TRI_index_s const*);
TRI_json_t* (*json) (struct TRI_index_s*, struct TRI_primary_collection_s const*);
void (*removeIndex) (struct TRI_index_s*, struct TRI_primary_collection_s*);
// .........................................................................................
// the following functions are called for transaction management
// .........................................................................................
int (*beginTransaction) (struct TRI_index_s*, struct TRI_primary_collection_s*);
int (*abortTransaction) (struct TRI_index_s*, struct TRI_primary_collection_s*);
int (*commitTransaction) (struct TRI_index_s*, struct TRI_primary_collection_s*);
// .........................................................................................
// the following functions are called for document/collection administration
// .........................................................................................
int (*insert) (struct TRI_index_s*, struct TRI_doc_mptr_s const*, const bool);
int (*remove) (struct TRI_index_s*, struct TRI_doc_mptr_s const*, const bool);
// NULL by default. will only be called if non-NULL
int (*postInsert) (struct TRI_transaction_collection_s*, struct TRI_index_s*, struct TRI_doc_mptr_s const*);
// a garbage collection function for the index
int (*cleanup) (struct TRI_index_s*);
// .........................................................................................
// the following functions are called by the query machinery which attempting to determine an
// appropriate index and when using the index to obtain a result set.
// .........................................................................................
// stores the usefulness of this index for the indicated query in the struct TRI_index_challenge_s
// returns integer which maps to set of errors.
// the actual type is:
// int (*indexQuery) (void*, struct TRI_index_operator_s*, struct TRI_index_challenge_s*, void*);
// first parameter is the specific index structure, e.g. HashIndex, SkiplistIndex etc
// fourth parameter is any internal storage which is/will be allocated as a consequence of this call
TRI_index_query_method_call_t indexQuery;
// returns the result set in an iterator
// the actual type is:
// TRI_index_iterator_t* (*indexQueryResult) (void*, struct TRI_index_operator_s*, void*, bool (*filter) (TRI_index_iterator_t*) );
// first parameter is the specific index structure, e.g. HashIndex, SkiplistIndex etc
// third parameter is any internal storage might have been allocated as a consequence of this or the indexQuery call above
// fourth parameter a filter which the index iterator should apply
TRI_index_query_result_method_call_t indexQueryResult;
// during the query or result function call, the index may have created and used
// additional storage, this method attempts to free this if required.
// the actual type is:
// void (*indexQueryFree) (struct TRI_index_s*, void*);
// second parameter is any internal storage might have been allocated as a consequence of the indexQuery
// or indexQueryResult calls above
TRI_index_query_free_method_call_t indexQueryFree;
}
TRI_index_t;
////////////////////////////////////////////////////////////////////////////////
/// @brief geo index
////////////////////////////////////////////////////////////////////////////////
typedef struct TRI_geo_index_s {
TRI_index_t base;
TRI_index_geo_variant_e _variant;
GeoIndex* _geoIndex;
TRI_shape_pid_t _location;
TRI_shape_pid_t _latitude;
TRI_shape_pid_t _longitude;
bool _geoJson;
bool _constraint;
}
TRI_geo_index_t;
////////////////////////////////////////////////////////////////////////////////
/// @brief edge index
////////////////////////////////////////////////////////////////////////////////
typedef struct TRI_edge_index_s {
TRI_index_t base;
TRI_multi_pointer_t _edges;
}
TRI_edge_index_t;
////////////////////////////////////////////////////////////////////////////////
/// @brief skiplist index
////////////////////////////////////////////////////////////////////////////////
typedef struct TRI_priorityqueue_index_s {
TRI_index_t base;
PQIndex* _pqIndex;
TRI_vector_t _paths; // a list of shape pid which identifies the fields of the index
}
TRI_priorityqueue_index_t;
////////////////////////////////////////////////////////////////////////////////
/// @brief skiplist index
////////////////////////////////////////////////////////////////////////////////
typedef struct TRI_skiplist_index_s {
TRI_index_t base;
SkiplistIndex* _skiplistIndex; // effectively the skiplist
TRI_vector_t _paths; // a list of shape pid which identifies the fields of the index
}
TRI_skiplist_index_t;
////////////////////////////////////////////////////////////////////////////////
/// @brief skiplistEx index supports transactions
////////////////////////////////////////////////////////////////////////////////
#ifdef TRI_SKIPLIST_EX
typedef struct TRI_skiplistEx_index_s {
TRI_index_t base;
SkiplistExIndex* _skiplistExIndex; // effectively the skiplist
TRI_vector_t _paths; // a list of shape pid which identifies the fields of the index
}
TRI_skiplistEx_index_t;
#endif
////////////////////////////////////////////////////////////////////////////////
/// @brief fulltext index
////////////////////////////////////////////////////////////////////////////////
typedef struct TRI_fulltext_index_s {
TRI_index_t base;
TRI_fts_index_t* _fulltextIndex;
TRI_shape_pid_t _attribute;
int _minWordLength;
bool _indexSubstrings;
}
TRI_fulltext_index_t;
////////////////////////////////////////////////////////////////////////////////
/// @brief cap constraint
////////////////////////////////////////////////////////////////////////////////
typedef struct TRI_cap_constraint_s {
TRI_index_t base;
size_t _count;
int64_t _size;
}
TRI_cap_constraint_t;
////////////////////////////////////////////////////////////////////////////////
/// @brief bitarray index
////////////////////////////////////////////////////////////////////////////////
typedef struct TRI_bitarray_index_s {
TRI_index_t base;
BitarrayIndex* _bitarrayIndex;
TRI_vector_t _paths; // a list of shape pid which identifies the fields of the index
TRI_vector_t _values; // a list of json objects which match the list of attributes used by the index
bool _supportUndef; // allows documents which do not match the attribute list to be indexed
}
TRI_bitarray_index_t;
////////////////////////////////////////////////////////////////////////////////
/// @brief index query result
////////////////////////////////////////////////////////////////////////////////
typedef struct TRI_index_result_s {
size_t _length;
struct TRI_doc_mptr_s** _documents; // simple list of elements
}
TRI_index_result_t;
////////////////////////////////////////////////////////////////////////////////
/// @brief index query parameter
////////////////////////////////////////////////////////////////////////////////
typedef struct TRI_index_search_value_s {
size_t _length;
TRI_shaped_json_t* _values;
}
TRI_index_search_value_t;
////////////////////////////////////////////////////////////////////////////////
/// @}
////////////////////////////////////////////////////////////////////////////////
// -----------------------------------------------------------------------------
// --SECTION-- INDEX
// -----------------------------------------------------------------------------
// -----------------------------------------------------------------------------
// --SECTION-- constructors and destructors
// -----------------------------------------------------------------------------
////////////////////////////////////////////////////////////////////////////////
/// @addtogroup VocBase
/// @{
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// @brief initialise basic index properties
////////////////////////////////////////////////////////////////////////////////
void TRI_InitIndex (TRI_index_t*,
const TRI_idx_type_e,
struct TRI_primary_collection_s*,
bool,
bool);
////////////////////////////////////////////////////////////////////////////////
/// @}
////////////////////////////////////////////////////////////////////////////////
// -----------------------------------------------------------------------------
// --SECTION-- public functions
// -----------------------------------------------------------------------------
////////////////////////////////////////////////////////////////////////////////
/// @addtogroup VocBase
/// @{
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// @brief free an index
////////////////////////////////////////////////////////////////////////////////
void TRI_FreeIndex (TRI_index_t* const);
////////////////////////////////////////////////////////////////////////////////
/// @brief removes an index file
////////////////////////////////////////////////////////////////////////////////
bool TRI_RemoveIndexFile (struct TRI_primary_collection_s*,
TRI_index_t*);
////////////////////////////////////////////////////////////////////////////////
/// @brief saves an index
////////////////////////////////////////////////////////////////////////////////
int TRI_SaveIndex (struct TRI_primary_collection_s*,
TRI_index_t*,
TRI_server_id_t);
////////////////////////////////////////////////////////////////////////////////
/// @brief looks up an index identifier
////////////////////////////////////////////////////////////////////////////////
TRI_index_t* TRI_LookupIndex (struct TRI_primary_collection_s*,
TRI_idx_iid_t);
////////////////////////////////////////////////////////////////////////////////
/// @brief creates a basic index description as JSON
/// this only contains the common index fields and needs to be extended by the
/// specialised index
////////////////////////////////////////////////////////////////////////////////
TRI_json_t* TRI_JsonIndex (TRI_memory_zone_t*,
TRI_index_t*);
////////////////////////////////////////////////////////////////////////////////
/// @brief destroys a result set returned by a hash index query
////////////////////////////////////////////////////////////////////////////////
void TRI_DestroyIndexResult (TRI_index_result_t*);
////////////////////////////////////////////////////////////////////////////////
/// @brief copies a path vector
////////////////////////////////////////////////////////////////////////////////
void TRI_CopyPathVector (TRI_vector_t*,
TRI_vector_t*);
////////////////////////////////////////////////////////////////////////////////
/// @brief copies all pointers from a vector
////////////////////////////////////////////////////////////////////////////////
void TRI_CopyFieldsVector (TRI_vector_string_t*,
TRI_vector_pointer_t*);
////////////////////////////////////////////////////////////////////////////////
/// @brief converts a path vector into a field list
///
/// Note that you must free the field list itself, but not the fields. The
/// belong to the shaper.
////////////////////////////////////////////////////////////////////////////////
char const** TRI_FieldListByPathList (TRI_shaper_t*,
TRI_vector_t*);
////////////////////////////////////////////////////////////////////////////////
/// @}
////////////////////////////////////////////////////////////////////////////////
// -----------------------------------------------------------------------------
// --SECTION-- PRIMARY INDEX
// -----------------------------------------------------------------------------
////////////////////////////////////////////////////////////////////////////////
/// @addtogroup VocBase
/// @{
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// @brief create the primary index
////////////////////////////////////////////////////////////////////////////////
TRI_index_t* TRI_CreatePrimaryIndex (struct TRI_primary_collection_s*);
////////////////////////////////////////////////////////////////////////////////
/// @brief destroys a primary index, but does not free the pointer
////////////////////////////////////////////////////////////////////////////////
void TRI_DestroyPrimaryIndex (TRI_index_t*);
////////////////////////////////////////////////////////////////////////////////
/// @brief free a primary index
////////////////////////////////////////////////////////////////////////////////
void TRI_FreePrimaryIndex (TRI_index_t*);
////////////////////////////////////////////////////////////////////////////////
/// @}
////////////////////////////////////////////////////////////////////////////////
// -----------------------------------------------------------------------------
// --SECTION-- EDGE INDEX
// -----------------------------------------------------------------------------
////////////////////////////////////////////////////////////////////////////////
/// @addtogroup VocBase
/// @{
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// @brief create the edge index
////////////////////////////////////////////////////////////////////////////////
TRI_index_t* TRI_CreateEdgeIndex (struct TRI_primary_collection_s*);
////////////////////////////////////////////////////////////////////////////////
/// @brief destroys an edge index, but does not free the pointer
////////////////////////////////////////////////////////////////////////////////
void TRI_DestroyEdgeIndex (TRI_index_t*);
////////////////////////////////////////////////////////////////////////////////
/// @brief free an edge index
////////////////////////////////////////////////////////////////////////////////
void TRI_FreeEdgeIndex (TRI_index_t*);
////////////////////////////////////////////////////////////////////////////////
/// @}
////////////////////////////////////////////////////////////////////////////////
// -----------------------------------------------------------------------------
// --SECTION-- PRIORITY QUEUE INDEX
// -----------------------------------------------------------------------------
// -----------------------------------------------------------------------------
// --SECTION-- constructors and destructors
// -----------------------------------------------------------------------------
////////////////////////////////////////////////////////////////////////////////
/// @addtogroup VocBase
/// @{
////////////////////////////////////////////////////////////////////////////////
PQIndexElements* TRI_LookupPriorityQueueIndex (TRI_index_t*,
size_t);
////////////////////////////////////////////////////////////////////////////////
/// @brief creates a priority queue index
////////////////////////////////////////////////////////////////////////////////
TRI_index_t* TRI_CreatePriorityQueueIndex (struct TRI_primary_collection_s*,
TRI_vector_pointer_t*,
TRI_vector_t*,
bool);
////////////////////////////////////////////////////////////////////////////////
/// @brief frees the memory allocated, but does not free the pointer
////////////////////////////////////////////////////////////////////////////////
void TRI_DestroyPriorityQueueIndex (TRI_index_t*);
////////////////////////////////////////////////////////////////////////////////
/// @brief frees the memory allocated and frees the pointer
////////////////////////////////////////////////////////////////////////////////
void TRI_FreePriorityQueueIndex (TRI_index_t*);
////////////////////////////////////////////////////////////////////////////////
/// @}
////////////////////////////////////////////////////////////////////////////////
// -----------------------------------------------------------------------------
// --SECTION-- SKIPLIST INDEX
// -----------------------------------------------------------------------------
// -----------------------------------------------------------------------------
// --SECTION-- constructors and destructors
// -----------------------------------------------------------------------------
////////////////////////////////////////////////////////////////////////////////
/// @addtogroup VocBase
/// @{
////////////////////////////////////////////////////////////////////////////////
TRI_skiplist_iterator_t* TRI_LookupSkiplistIndex (TRI_index_t*,
TRI_index_operator_t*);
////////////////////////////////////////////////////////////////////////////////
/// @brief creates a skiplist index
////////////////////////////////////////////////////////////////////////////////
TRI_index_t* TRI_CreateSkiplistIndex (struct TRI_primary_collection_s*,
TRI_vector_pointer_t* fields,
TRI_vector_t* paths,
bool unique);
////////////////////////////////////////////////////////////////////////////////
/// @brief frees the memory allocated, but does not free the pointer
////////////////////////////////////////////////////////////////////////////////
void TRI_DestroySkiplistIndex (TRI_index_t* idx);
////////////////////////////////////////////////////////////////////////////////
/// @brief frees the memory allocated and frees the pointer
////////////////////////////////////////////////////////////////////////////////
void TRI_FreeSkiplistIndex (TRI_index_t* idx);
////////////////////////////////////////////////////////////////////////////////
/// @}
////////////////////////////////////////////////////////////////////////////////
// -----------------------------------------------------------------------------
// --SECTION-- FULLTEXT INDEX
// -----------------------------------------------------------------------------
// -----------------------------------------------------------------------------
// --SECTION-- constructors and destructors
// -----------------------------------------------------------------------------
////////////////////////////////////////////////////////////////////////////////
/// @addtogroup VocBase
/// @{
////////////////////////////////////////////////////////////////////////////////
struct TRI_doc_mptr_s** TRI_LookupFulltextIndex (TRI_index_t*,
const char*);
////////////////////////////////////////////////////////////////////////////////
/// @brief creates a fulltext index
////////////////////////////////////////////////////////////////////////////////
TRI_index_t* TRI_CreateFulltextIndex (struct TRI_primary_collection_s*,
const char*,
const bool,
int);
////////////////////////////////////////////////////////////////////////////////
/// @brief frees the memory allocated, but does not free the pointer
////////////////////////////////////////////////////////////////////////////////
void TRI_DestroyFulltextIndex (TRI_index_t*);
////////////////////////////////////////////////////////////////////////////////
/// @brief frees the memory allocated and frees the pointer
////////////////////////////////////////////////////////////////////////////////
void TRI_FreeFulltextIndex (TRI_index_t*);
////////////////////////////////////////////////////////////////////////////////
/// @}
////////////////////////////////////////////////////////////////////////////////
// -----------------------------------------------------------------------------
// --SECTION-- BITARRAY INDEX
// -----------------------------------------------------------------------------
// -----------------------------------------------------------------------------
// --SECTION-- constructors and destructors
// -----------------------------------------------------------------------------
////////////////////////////////////////////////////////////////////////////////
/// @addtogroup VocBase
/// @{
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
/// @brief returns an iterator for a lookup query
////////////////////////////////////////////////////////////////////////////////
TRI_index_iterator_t* TRI_LookupBitarrayIndex (TRI_index_t*,
TRI_index_operator_t*,
bool (*filter) (TRI_index_iterator_t*) );
////////////////////////////////////////////////////////////////////////////////
/// @brief creates a bitarray index
////////////////////////////////////////////////////////////////////////////////
TRI_index_t* TRI_CreateBitarrayIndex (struct TRI_primary_collection_s*,
TRI_vector_pointer_t*,
TRI_vector_t*,
TRI_vector_pointer_t*,
bool,
int*,
char**);
////////////////////////////////////////////////////////////////////////////////
/// @brief frees the memory allocated, but does not free the pointer
////////////////////////////////////////////////////////////////////////////////
void TRI_DestroyBitarrayIndex (TRI_index_t*);
////////////////////////////////////////////////////////////////////////////////
/// @brief frees the memory allocated and frees the pointer
////////////////////////////////////////////////////////////////////////////////
void TRI_FreeBitarrayIndex (TRI_index_t*);
////////////////////////////////////////////////////////////////////////////////
/// @}
////////////////////////////////////////////////////////////////////////////////
#ifdef __cplusplus
}
#endif
#endif
// Local Variables:
// mode: outline-minor
// outline-regexp: "/// @brief\\|/// {@inheritDoc}\\|/// @addtogroup\\|/// @page\\|// --SECTION--\\|/// @\\}"
// End: