mirror of https://gitee.com/bigwinds/arangodb
332 lines
14 KiB
Plaintext
332 lines
14 KiB
Plaintext
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief simple queries
|
|
///
|
|
/// @file
|
|
///
|
|
/// DISCLAIMER
|
|
///
|
|
/// Copyright 2012 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 2012, triAGENS GmbH, Cologne, Germany
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
// -----------------------------------------------------------------------------
|
|
// --SECTION-- SIMPLE QUERIES
|
|
// -----------------------------------------------------------------------------
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @page SimpleQueriesTOC
|
|
///
|
|
/// <ul>
|
|
/// <li>@ref SimpleQueries
|
|
/// <ul>
|
|
/// <li>@ref SimpleQueriesQueries
|
|
/// <ul>
|
|
/// <li>@ref SimpleQueryAll "collection.all"</li>
|
|
/// <li>@ref SimpleQueryByExample "collection.byExample"</li>
|
|
/// <li>@ref SimpleQueryFirstExample "collection.firstExample"</li>
|
|
/// <li>@ref SimpleQueryRange "collection.range"</li>
|
|
/// <li>@ref SimpleQueryAny "collection.any"</li>
|
|
/// <li>@ref SimpleQueryCollectionCount "collection.count"</li>
|
|
/// <li>@ref SimpleQueryToArray "collection.toArray"</li>
|
|
/// </ul>
|
|
/// </li>
|
|
/// <li>@ref SimpleQueriesGeoQueries
|
|
/// <ul>
|
|
/// <li>@ref SimpleQueryNear "collection.near"</li>
|
|
/// <li>@ref SimpleQueryWithin "collection.within"</li>
|
|
/// <li>@ref SimpleQueryGeo "collection.geo"</li>
|
|
/// </ul>
|
|
/// </li>
|
|
/// <li>@ref SimpleQueriesFulltext
|
|
/// <ul>
|
|
/// <li>@ref SimpleQueryFulltext "collection.fulltext"</li>
|
|
/// </ul>
|
|
/// </li>
|
|
/// <li>@ref SimpleQueriesPagination
|
|
/// <ul>
|
|
/// <li>@ref SimpleQueryLimit "query.limit"</li>
|
|
/// <li>@ref SimpleQuerySkip "query.skip"</li>
|
|
/// </ul>
|
|
/// </li>
|
|
/// <li>@ref SimpleQueriesCursor
|
|
/// <ul>
|
|
/// <li>@ref SimpleQueryHasNext "query.hasNext"</li>
|
|
/// <li>@ref SimpleQueryNext "query.next"</li>
|
|
/// <li>@ref SimpleQuerySetBatchSize "query.setBatchSize"</li>
|
|
/// <li>@ref SimpleQueryGetBatchSize "query.getBatchSize"</li>
|
|
/// <li>@ref SimpleQueryExecute "query.execute"</li>
|
|
/// <li>@ref SimpleQueryDispose "query.dispose"</li>
|
|
/// <li>@ref SimpleQueryCount "query.count"</li>
|
|
/// </ul>
|
|
/// </li>
|
|
/// <li>@ref SimpleQueriesModify
|
|
/// <ul>
|
|
/// <li>@ref SimpleQueryRemoveByExample "collection.removeByExample"</li>
|
|
/// </ul>
|
|
/// </li>
|
|
/// </ul>
|
|
/// </li>
|
|
/// </ul>
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @page SimpleQueries Simple Queries
|
|
///
|
|
/// @NAVIGATE_SimpleQueries
|
|
///
|
|
/// Simple queries can be used if the query condition is straight forward,
|
|
/// i.e., a document reference, all documents, a query-by-example, or a simple
|
|
/// geo query. In a simple query you can specify exactly one collection and one
|
|
/// query criteria. In the following sections we describe the JavaScript shell
|
|
/// interface for simple queries, which you can use within the ArangoDB shell
|
|
/// and within actions and transactions. For other languages see the
|
|
/// corresponding language API documentation.
|
|
///
|
|
/// If a query returns a cursor, then you can use @FN{hasNext} and @FN{next} to
|
|
/// iterate over the result set or @FN{toArray} to convert it to an array.
|
|
///
|
|
/// If the number of query results is expected to be big, it is possible to
|
|
/// limit the amount of documents transferred between the server and the client
|
|
/// to a specific value. This value is called @LIT{batchSize}. The @LIT{batchSize}
|
|
/// can optionally be set before or when a simple query is executed.
|
|
/// If the server has more documents than should be returned in a single batch,
|
|
/// the server will set the @LIT{hasMore} attribute in the result. It will also
|
|
/// return the id of the server-side cursor in the @LIT{id} attribute in the result.
|
|
/// This id can be used with the cursor API to fetch any outstanding results from
|
|
/// the server and dispose the server-side cursor afterwards.
|
|
///
|
|
/// The initial @LIT{batchSize} value can be set using the @FN{setBatchSize}
|
|
/// method that is available for each type of simple query, or when the simple
|
|
/// query is executed using its @FN{execute} method. If no @LIT{batchSize} value
|
|
/// is specified, the server will pick a reasonable default value.
|
|
///
|
|
/// @EMBEDTOC{ SimpleQueriesTOC}
|
|
///
|
|
/// @CLEARPAGE
|
|
/// @section SimpleQueriesQueries Queries
|
|
/////////////////////////////////////////
|
|
///
|
|
/// @anchor SimpleQueryAll
|
|
/// @copydetails JSF_ArangoCollection_prototype_all
|
|
///
|
|
/// @CLEARPAGE
|
|
/// @anchor SimpleQueryByExample
|
|
/// @copydetails JSF_ArangoCollection_prototype_byExample
|
|
///
|
|
/// @CLEARPAGE
|
|
/// @anchor SimpleQueryFirstExample
|
|
/// @copydetails JSF_ArangoCollection_prototype_firstExample
|
|
///
|
|
/// @CLEARPAGE
|
|
/// @anchor SimpleQueryAny
|
|
/// @copydetails JSF_ArangoCollection_prototype_range
|
|
///
|
|
/// @CLEARPAGE
|
|
/// @anchor SimpleQueryRange
|
|
/// @copydetails JS_AnyQuery
|
|
///
|
|
/// @CLEARPAGE
|
|
/// @anchor SimpleQueryCollectionCount
|
|
/// @copydetails JS_CountVocbaseCol
|
|
///
|
|
/// @CLEARPAGE
|
|
/// @anchor SimpleQueryToArray
|
|
/// @copydetails JSF_ArangoCollection_prototype_toArray
|
|
///
|
|
/// @CLEARPAGE
|
|
/// @section SimpleQueriesGeoQueries Geo Queries
|
|
////////////////////////////////////////////////
|
|
///
|
|
/// The ArangoDB allows to select documents based on geographic coordinates. In
|
|
/// order for this to work, a geo-spatial index must be defined. This index
|
|
/// will use a very elaborate algorithm to lookup neighbors that is a magnitude
|
|
/// faster than a simple R* index.
|
|
///
|
|
/// In general a geo coordinate is a pair of latitude and longitude. This can
|
|
/// either be a list with two elements like @LIT{[-10\, +30]} (latitude
|
|
/// first, followed by longitude) or an object like @LIT{{lon: -10\, lat: +30}}.
|
|
/// In order to find all documents within a given radius around a coordinate
|
|
/// use the @FN{within} operator. In order to find all documents near a given
|
|
/// document use the @FN{near} operator.
|
|
///
|
|
/// It is possible to define more than one geo-spatial index per collection. In
|
|
/// this case you must give a hint using the @FN{geo} operator which of indexes
|
|
/// should be used in a query.
|
|
///
|
|
/// @CLEARPAGE
|
|
/// @anchor SimpleQueryNear
|
|
/// @copydetails JSF_ArangoCollection_prototype_near
|
|
///
|
|
/// @CLEARPAGE
|
|
/// @anchor SimpleQueryWithin
|
|
/// @copydetails JSF_ArangoCollection_prototype_within
|
|
///
|
|
/// @CLEARPAGE
|
|
/// @anchor SimpleQueryGeo
|
|
/// @copydetails JSF_ArangoCollection_prototype_geo
|
|
///
|
|
///
|
|
/// @CLEARPAGE
|
|
/// @section SimpleQueriesFulltext Fulltext queries
|
|
///////////////////////////////////////////////////
|
|
///
|
|
/// ArangoDB allows to run queries on text contained in document attributes.
|
|
/// To use this, a fulltext index must be defined for the attribute of the
|
|
/// collection that contains the text. Creating the index will parse the text
|
|
/// in the specified attribute for all documents of the collection. Only documents
|
|
/// will be indexed that contain a textual value in the indexed attribute.
|
|
/// For such documents, the text value will be parsed, and the individual words
|
|
/// will be inserted into the fulltext index.
|
|
///
|
|
/// When a fulltext index exists, it can be queried using a fulltext query.
|
|
///
|
|
/// @CLEARPAGE
|
|
/// @anchor SimpleQueryFulltext
|
|
/// @copydetails JSF_ArangoCollection_prototype_fulltext
|
|
///
|
|
/// Fulltext query syntax:
|
|
///
|
|
/// In the simplest form, a fulltext query contains just the sought word. If
|
|
/// multiple search words are given in a query, they should be separated by commas.
|
|
/// All search words will be combined with a logical AND by default, and only
|
|
/// such documents will be returned that contain all search words. This default
|
|
/// behavior can be changed by providing the extra control characters in the fulltext
|
|
/// query, which are:
|
|
/// - @LIT{+}: logical AND (intersection)
|
|
/// - @LIT{|}: logical OR (union)
|
|
/// - @LIT{-}: negation (exclusion)
|
|
///
|
|
/// Examples:
|
|
/// - @LIT{"banana"}: searches for documents containing "banana"
|
|
/// - @LIT{"banana,apple"}: searches for documents containing both "banana" AND "apple"
|
|
/// - @LIT{"banana,|orange"}: searches for documents containing eihter "banana" OR "orange"
|
|
/// (or both)
|
|
/// - @LIT{"banana,-apple"}: searches for documents that contain "banana" but NOT "apple".
|
|
/// Logical operators are evaluated from left to right.
|
|
///
|
|
/// Each search word can optionally be prefixed with @LIT{complete:} or @LIT{prefix:},
|
|
/// with @LIT{complete:} being the default. This allows searching for complete words or
|
|
/// for word prefixes. Suffix searches or any other forms are partial-word matching are
|
|
/// currently not supported.
|
|
///
|
|
/// Examples:
|
|
/// - @LIT{"complete:banana"}: searches for documents containing the exact word "banana"
|
|
/// - @LIT{"prefix:head"}: searches for documents with words that start with prefix "head"
|
|
/// - @LIT{"prefix:head,banana"}: searches for documents contain words starting with prefix
|
|
/// "head" and that also contain the exact word "banana".
|
|
///
|
|
/// Complete match and prefix search options can be combined with the logical operators.
|
|
///
|
|
/// Please note that only words with a minimum length will get indexed. This minimum length
|
|
/// can be defined when creating the fulltext index. For words tokenisation, the libicu
|
|
/// text boundary analysis is used, which takes into account the default as defined at
|
|
/// server startup (@LIT{--server.default-language} startup option). Generally, the word
|
|
/// boundary analysis will filter out punctuation but will not do much more.
|
|
///
|
|
/// Especially no Word normalisation, stemming, or similarity analysises will be performed
|
|
/// when indexing or searching. If any of these features is required, it is suggested that
|
|
/// the user does the text normalisation on the client side, and provides for each document
|
|
/// an extra attribute containing just a comma-separated list of normalised words. This
|
|
/// attribute can then be indexed with a fulltext index, and the user can send fulltext
|
|
/// queries for this index, with the fulltext queries also containing the stemmed or
|
|
/// normalised versions of words as required by the user.
|
|
///
|
|
///
|
|
/// @CLEARPAGE
|
|
/// @section SimpleQueriesPagination Pagination
|
|
///////////////////////////////////////////////
|
|
///
|
|
/// If, for example, you display the result of a user search, then you are in
|
|
/// general not interested in the completed result set, but only the first 10 or
|
|
/// so documents. Or maybe the next 10 documents for the second page. In this
|
|
/// case, you can the @FN{skip} and @FN{limit} operators. These operators work
|
|
/// like LIMIT in MySQL.
|
|
///
|
|
/// @FN{skip} used together with @FN{limit} can be used to implement pagination.
|
|
/// The @FN{skip} operator skips over the first n documents. So, in order to
|
|
/// create result pages with 10 result documents per page, you can use
|
|
/// @LIT{skip(n * 10).limit(10)} to access the 10 documents on the n.th page.
|
|
/// This result should be sorted, so that the pagination works in a predicable
|
|
/// way.
|
|
///
|
|
/// @CLEARPAGE
|
|
/// @anchor SimpleQueryLimit
|
|
/// @copydetails JSF_SimpleQuery_prototype_limit
|
|
///
|
|
/// @CLEARPAGE
|
|
/// @anchor SimpleQuerySkip
|
|
/// @copydetails JSF_SimpleQuery_prototype_skip
|
|
///
|
|
/// @CLEARPAGE
|
|
/// @section SimpleQueriesCursor Sequential Access and Cursors
|
|
//////////////////////////////////////////////////////////////
|
|
///
|
|
/// @anchor SimpleQueryHasNext
|
|
/// @copydetails JSF_SimpleQuery_prototype_hasNext
|
|
///
|
|
/// @CLEARPAGE
|
|
/// @anchor SimpleQueryNext
|
|
/// @copydetails JSF_SimpleQuery_prototype_next
|
|
///
|
|
/// @CLEARPAGE
|
|
/// @anchor SimpleQuerySetBatchSize
|
|
/// @copydetails JSF_SimpleQuery_prototype_setBatchSize
|
|
///
|
|
/// @CLEARPAGE
|
|
/// @anchor SimpleQueryGetBatchSize
|
|
/// @copydetails JSF_SimpleQuery_prototype_getBatchSize
|
|
///
|
|
/// @CLEARPAGE
|
|
/// @anchor SimpleQueryExecute
|
|
/// @copydetails JSF_SimpleQuery_prototype_execute
|
|
///
|
|
/// @CLEARPAGE
|
|
/// @anchor SimpleQueryDispose
|
|
/// @copydetails JSF_SimpleQuery_prototype_dispose
|
|
///
|
|
/// @CLEARPAGE
|
|
/// @anchor SimpleQueryCount
|
|
/// @copydetails JSF_SimpleQuery_prototype_count
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
///
|
|
/// @CLEARPAGE
|
|
/// @section SimpleQueriesModify Modification Queries
|
|
/////////////////////////////////////////////////////
|
|
///
|
|
/// ArangoDB also allows removing documents based on an example document.
|
|
/// Every document in the collection will be compared against the specified
|
|
/// example document and be deleted if all attributes match.
|
|
///
|
|
/// This method should be used with caution as it intended to remove lots of
|
|
/// documents from a collection.
|
|
///
|
|
/// @CLEARPAGE
|
|
/// @anchor SimpleQueryRemoveByExample
|
|
/// @copydetails JSF_ArangoCollection_prototype_removeByExample
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
// -----------------------------------------------------------------------------
|
|
// --SECTION-- END-OF-FILE
|
|
// -----------------------------------------------------------------------------
|
|
|
|
// Local Variables:
|
|
// mode: outline-minor
|
|
// outline-regexp: "^\\(/// @brief\\|/// {@inheritDoc}\\|/// @addtogroup\\|// --SECTION--\\|/// @page\\|/// @\\}\\)"
|
|
// End:
|