mirror of https://gitee.com/bigwinds/arangodb
203 lines
8.3 KiB
Plaintext
203 lines
8.3 KiB
Plaintext
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief statements and cursors
|
|
///
|
|
/// @file
|
|
///
|
|
/// DISCLAIMER
|
|
///
|
|
/// Copyright 2010-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 Jan Steemann
|
|
/// @author Copyright 2012, triagens GmbH, Cologne, Germany
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @page RestCursor REST Interface for select queries and cursors
|
|
///
|
|
/// @section RestCursorExecute Executing a query
|
|
///
|
|
/// To run a select query, the query details need to be shipped from the client
|
|
/// to the server via a HTTP POST request.
|
|
///
|
|
/// @anchor RestCursorPost
|
|
/// @REST{POST /_api/cursor}
|
|
///
|
|
/// The query details include the query string plus optional query options and
|
|
/// bind parameters. These values need to be passed in a JSON representation
|
|
/// in the body of the POST request.
|
|
///
|
|
/// The following attributes can be used inside the JSON object:
|
|
/// - query: contains the query string to be executed (mandatory)
|
|
/// - count: boolean flag that indicates whether the number of documents
|
|
/// found should be returned as "count" attribute in the result set
|
|
/// (optional).
|
|
/// Calculating the "count" attribute might have a performance penalty for
|
|
/// some queries so this option is turned off by default.
|
|
/// - batchSize: maximum number of result documents to be transferred from
|
|
/// the server to the client in one roundtrip (optional). If this attribute
|
|
/// is not set, a server-controlled default value will be used.
|
|
/// - bindVars: key/value list of bind parameters (optional).
|
|
///
|
|
/// @verbinclude cursor
|
|
///
|
|
/// If the JSON representation is malformed or the query specification is missing
|
|
/// from the request, the server will respond with @LIT{HTTP 400} or @LIT{HTTP 404}.
|
|
///
|
|
/// @verbinclude cursor4001
|
|
///
|
|
/// @verbinclude cursor4002
|
|
///
|
|
/// The body of the response will contain a JSON object with additional error
|
|
/// details. The object has the following attributes:
|
|
/// - error: boolean flag to indicate that an error occurred (true in this case)
|
|
/// - code: the HTTP status code
|
|
/// - errorNum: the server error number
|
|
/// - errorMessage: a descriptive error message
|
|
///
|
|
/// If the query specification is complete, the server will process the query. If an
|
|
/// error occurs during query processing, the server will respond with @LIT{HTTP 404}.
|
|
/// Again, the body of the response will contain details about the error.
|
|
///
|
|
/// @verbinclude cursor404
|
|
///
|
|
/// A list of query errors can be found @ref AvocadoErrors here.
|
|
///
|
|
/// If the result set can be created by the server, the server will respond with
|
|
/// @LIT{HTTP 201}. The body of the response will contain a JSON object with the
|
|
/// result set.
|
|
///
|
|
/// The JSON object has the following properties:
|
|
/// - error: boolean flag to indicate that an error occurred (false in this case)
|
|
/// - code: the HTTP status code
|
|
/// - result: an array of result documents (might be empty if query has no results)
|
|
/// - hasMore: a boolean indicator whether there are more results available on the
|
|
/// server
|
|
/// - count: the total number of result documents available (only available if the
|
|
/// query was executed with the @LIT{count} attribute set.
|
|
/// - _id: id of temporary cursor created on the server (optional, see below)
|
|
///
|
|
/// @verbinclude cursor201
|
|
///
|
|
/// @section RestCursorResults Retrieving query results
|
|
///
|
|
/// Select queries are executed on-the-fly on the server and the result set will
|
|
/// be returned back to the client.
|
|
///
|
|
/// There are two ways the client can get the result set from the server:
|
|
/// - in a single roundtrip
|
|
/// - using a cursor
|
|
///
|
|
/// @subsection RestCursorResultsSingle Single roundtrip
|
|
///
|
|
/// The server will only transfer a certain number of result documents back to
|
|
/// the client in one roundtrip. This number is controllable by the client by
|
|
/// setting the @LIT{batchSize} attribute when issueing the query.
|
|
///
|
|
/// If the complete result can be transferred to the client in one go, the client
|
|
/// does not need to issue any further request. The client can check whether
|
|
/// it has retrieved the complete result set by checking the @LIT{hasMore}
|
|
/// attribute of the result set. If it is set to false, then the client has
|
|
/// fetched the complete result set from the server.
|
|
///
|
|
/// @subsection RestCursorResultsCursor Using a Cursor
|
|
///
|
|
/// If the result set contains more documents than should be transferred in a
|
|
/// single roundtrip (i.e. as set via the @LIT{batchSize} attribute), the
|
|
/// server will return the first few documents and create a temporary cursor.
|
|
/// The cursor id will also be returned to the client. The server will put
|
|
/// the cursor id in the @LIT{_id} attribute of the response object.
|
|
/// Furthermore, the @LIT{hasMore} attribute of the response object will be
|
|
/// set to @LIT{true}. This is an indication for the client that there are
|
|
/// additional results to fetch from the server.
|
|
///
|
|
/// @verbinclude cursorput1
|
|
///
|
|
/// @anchor RestCursorPut
|
|
/// @REST{PUT /_api/cursor/@FA{cursor-identifier}}
|
|
///
|
|
/// In this case, the client can use the cursor id to subsequently fetch the
|
|
/// remaining result documents from the server until there are no more documents
|
|
/// available. This is done by the client issueing additional HTTP PUT requests.
|
|
///
|
|
/// @verbinclude cursorput2
|
|
///
|
|
/// The server will respond with @LIT{HTTP 200} in case of success. If the
|
|
/// cursor id is ommitted or somehow invalid, the server will respond with
|
|
/// @LIT{HTTP 404}.
|
|
///
|
|
/// @verbinclude cursorputfail
|
|
///
|
|
/// Once the @LIT{hasMore} attribute has a value of @LIT{false}, the client can
|
|
/// stop.
|
|
///
|
|
/// @verbinclude cursorput3
|
|
///
|
|
/// @anchor RestCursorDelete
|
|
/// @REST{DELETE /_api/cursor/@FA{cursor-identifier}}
|
|
///
|
|
/// The cursor will be destroyed on the server when the client has retrieved
|
|
/// all documents from it. The client can also explicitly destroy the cursor
|
|
/// at any earlier time using an HTTP DELETE request. The cursor id must be
|
|
/// included as part of the URL.
|
|
///
|
|
/// @verbinclude cursordelete
|
|
///
|
|
/// In case the server is aware of the cursor, it will respond with
|
|
/// @LIT{HTTP 202}. Otherwise, it will respond with @LIT{404}.
|
|
///
|
|
/// Cursors that have been explicitly destroyed must not be used afterwards. If
|
|
/// a cursor is used after it has been destroyed, the server will respond with
|
|
/// @LIT{HTTP 404} as well.
|
|
///
|
|
/// @verbinclude cursordeletefail
|
|
///
|
|
/// Note: the server will also destroy abandoned cursors automatically after a
|
|
/// certain server-controlled timeout to avoid resource leakage.
|
|
///
|
|
/// @section RestQueryValidate Validating a query
|
|
///
|
|
/// To validate a query string without executing it, the query string can be
|
|
/// passed to the server via an HTTP POST request.
|
|
///
|
|
/// @anchor RestQueryPost
|
|
/// @REST{POST /_api/query}
|
|
///
|
|
/// These query string needs to be passed in the attribute @LIT{query} of a
|
|
/// JSON object as the body of the POST request.
|
|
///
|
|
/// The server will respond with @LIT{HTTP 400} or @LIT{HTTP 500} in case of a
|
|
/// malformed request or a general error.
|
|
/// If the query contains a parse error, the server will respond with an
|
|
/// @LIT{HTTP 404} error.
|
|
///
|
|
/// The body of the response will contain the error details embedded in a JSON
|
|
/// object.
|
|
///
|
|
/// @verbinclude querypostfail
|
|
///
|
|
/// If the query is valid, the server will respond with @LIT{HTTP 200} and return
|
|
/// the names of the bind parameters it found in the query (if any) in the
|
|
/// @LIT{"bindVars"} attribute of the response.
|
|
///
|
|
/// @verbinclude querypost
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
// Local Variables:
|
|
// mode: outline-minor
|
|
// outline-regexp: "^\\(/// @brief\\|/// {@inheritDoc}\\|/// @addtogroup\\|// --SECTION--\\|/// @\\}\\)"
|
|
// End:
|