mirror of https://gitee.com/bigwinds/arangodb
210 lines
6.9 KiB
Markdown
210 lines
6.9 KiB
Markdown
---
|
|
layout: default
|
|
description: Sequential Access and Cursors
|
|
---
|
|
Sequential Access and Cursors
|
|
=============================
|
|
|
|
If a query returns a cursor (for example by calling `db._query(...)`), then you can use *hasNext* and *next* to
|
|
iterate over the result set or *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 *batchSize*. The *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 *hasMore* attribute in the result. It will also
|
|
return the id of the server-side cursor in the *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 *batchSize* value can be set using the *setBatchSize*
|
|
method that is available for each type of simple query, or when the simple
|
|
query is executed using its *execute* method. If no *batchSize* value
|
|
is specified, the server will pick a reasonable default value.
|
|
|
|
Has Next
|
|
--------
|
|
|
|
<!-- js/common/modules/@arangodb/simple-query-common.js -->
|
|
|
|
|
|
checks if the cursor is exhausted
|
|
`cursor.hasNext()`
|
|
|
|
The *hasNext* operator returns *true*, then the cursor still has
|
|
documents. In this case the next document can be accessed using the
|
|
*next* operator, which will advance the cursor.
|
|
|
|
|
|
**Examples**
|
|
{% arangoshexample examplevar="examplevar" script="script" result="result" %}
|
|
|
|
@startDocuBlockInline cursorHasNext
|
|
@EXAMPLE_ARANGOSH_OUTPUT{cursorHasNext}
|
|
~ db._create("five");
|
|
~ db.five.save({ name : "one" });
|
|
~ db.five.save({ name : "two" });
|
|
~ db.five.save({ name : "three" });
|
|
~ db.five.save({ name : "four" });
|
|
~ db.five.save({ name : "five" });
|
|
var a = db._query("FOR x IN five RETURN x");
|
|
while (a.hasNext()) print(a.next());
|
|
~ db._drop("five")
|
|
@END_EXAMPLE_ARANGOSH_OUTPUT
|
|
@endDocuBlock cursorHasNext
|
|
{% endarangoshexample %}
|
|
{% include arangoshexample.html id=examplevar script=script result=result %}
|
|
|
|
Next
|
|
----
|
|
|
|
<!-- js/common/modules/@arangodb/simple-query-common.js -->
|
|
|
|
|
|
returns the next result document
|
|
`cursor.next()`
|
|
|
|
If the *hasNext* operator returns *true*, then the underlying
|
|
cursor of the simple query still has documents. In this case the
|
|
next document can be accessed using the *next* operator, which
|
|
will advance the underlying cursor. If you use *next* on an
|
|
exhausted cursor, then *undefined* is returned.
|
|
|
|
|
|
**Examples**
|
|
{% arangoshexample examplevar="examplevar" script="script" result="result" %}
|
|
|
|
@startDocuBlockInline cursorNext
|
|
@EXAMPLE_ARANGOSH_OUTPUT{cursorNext}
|
|
~ db._create("five");
|
|
~ db.five.save({ name : "one" });
|
|
~ db.five.save({ name : "two" });
|
|
~ db.five.save({ name : "three" });
|
|
~ db.five.save({ name : "four" });
|
|
~ db.five.save({ name : "five" });
|
|
db._query("FOR x IN five RETURN x").next();
|
|
~ db._drop("five")
|
|
@END_EXAMPLE_ARANGOSH_OUTPUT
|
|
@endDocuBlock cursorNext
|
|
{% endarangoshexample %}
|
|
{% include arangoshexample.html id=examplevar script=script result=result %}
|
|
|
|
Set Batch size
|
|
--------------
|
|
|
|
<!-- js/common/modules/@arangodb/simple-query-common.js -->
|
|
|
|
|
|
sets the batch size for any following requests
|
|
`cursor.setBatchSize(number)`
|
|
|
|
Sets the batch size for queries. The batch size determines how many results
|
|
are at most transferred from the server to the client in one chunk.
|
|
|
|
|
|
Get Batch size
|
|
--------------
|
|
|
|
<!-- js/common/modules/@arangodb/simple-query-common.js -->
|
|
|
|
|
|
returns the batch size
|
|
`cursor.getBatchSize()`
|
|
|
|
Returns the batch size for queries. If the returned value is undefined, the
|
|
server will determine a sensible batch size for any following requests.
|
|
|
|
|
|
Execute Query
|
|
-------------
|
|
|
|
<!-- js/common/modules/@arangodb/simple-query-common.js -->
|
|
|
|
|
|
executes a query
|
|
`query.execute(batchSize)`
|
|
|
|
Executes a simple query. If the optional batchSize value is specified,
|
|
the server will return at most batchSize values in one roundtrip.
|
|
The batchSize cannot be adjusted after the query is first executed.
|
|
|
|
**Note**: There is no need to explicitly call the execute method if another
|
|
means of fetching the query results is chosen. The following two approaches
|
|
lead to the same result:
|
|
{% arangoshexample examplevar="examplevar" script="script" result="result" %}
|
|
@startDocuBlockInline executeQueryNoBatchSize
|
|
@EXAMPLE_ARANGOSH_OUTPUT{executeQueryNoBatchSize}
|
|
~ db._create("users");
|
|
~ db.users.save({ name: "Gerhard" });
|
|
~ db.users.save({ name: "Helmut" });
|
|
~ db.users.save({ name: "Angela" });
|
|
result = db.users.all().toArray();
|
|
| var q = db._query("FOR x IN users RETURN x");
|
|
| result = [ ];
|
|
| while (q.hasNext()) {
|
|
| result.push(q.next());
|
|
}
|
|
~ db._drop("users")
|
|
@END_EXAMPLE_ARANGOSH_OUTPUT
|
|
@endDocuBlock executeQueryNoBatchSize
|
|
{% endarangoshexample %}
|
|
{% include arangoshexample.html id=examplevar script=script result=result %}
|
|
The following two alternatives both use a batchSize and return the same
|
|
result:
|
|
{% arangoshexample examplevar="examplevar" script="script" result="result" %}
|
|
@startDocuBlockInline executeQueryBatchSize
|
|
@EXAMPLE_ARANGOSH_OUTPUT{executeQueryBatchSize}
|
|
~ db._create("users");
|
|
~ db.users.save({ name: "Gerhard" });
|
|
~ db.users.save({ name: "Helmut" });
|
|
~ db.users.save({ name: "Angela" });
|
|
q = db.users.all(); q.setBatchSize(20); q.execute(); while (q.hasNext()) { print(q.next()); }
|
|
q = db.users.all(); q.execute(20); while (q.hasNext()) { print(q.next()); }
|
|
~ db._drop("users")
|
|
@END_EXAMPLE_ARANGOSH_OUTPUT
|
|
@endDocuBlock executeQueryBatchSize
|
|
{% endarangoshexample %}
|
|
{% include arangoshexample.html id=examplevar script=script result=result %}
|
|
|
|
|
|
Dispose
|
|
-------
|
|
|
|
<!-- js/common/modules/@arangodb/simple-query-common.js -->
|
|
|
|
|
|
disposes the result
|
|
`cursor.dispose()`
|
|
|
|
If you are no longer interested in any further results, you should call
|
|
*dispose* in order to free any resources associated with the cursor.
|
|
After calling *dispose* you can no longer access the cursor.
|
|
|
|
|
|
Count
|
|
-----
|
|
|
|
<!-- js/common/modules/@arangodb/simple-query-common.js -->
|
|
|
|
|
|
counts the number of documents
|
|
`cursor.count()`
|
|
|
|
The *count* operator counts the number of document in the result set and
|
|
returns that number. The *count* operator ignores any limits and returns
|
|
the total number of documents found.
|
|
|
|
**Note**: Not all simple queries support counting. In this case *null* is
|
|
returned (Simple queries are deprecated).
|
|
|
|
`cursor.count(true)`
|
|
|
|
If the result set was limited by the *limit* operator or documents were
|
|
skiped using the *skip* operator, the *count* operator with argument
|
|
*true* will use the number of elements in the final result set - after
|
|
applying *limit* and *skip*.
|
|
|
|
**Note**: Not all simple queries support counting. In this case *null* is
|
|
returned (Simple queries are deprecated)..
|