Datastore: runQuery limit/cursors usage not clear

[dwsupplee]

DatastoreClient::runQuery paginates through all results regardless of limit/cursors that are set. This leads to some slightly unexpected behavior in cases like the following:

// Assuming there are 5 results of kind 'Person'
$query = $datastore->query()
    ->kind('Person')
    ->limit(1);
$results = $datastore->runQuery($query);

echo count(iterator_to_array($results)); // 5

It takes more intimate knowledge of the library to realize that Query::limit() is only limiting the number of results per call to the API.

To limit the results returned from the API and only get a single item one must do the following:

$limit = 1;
$query = $datastore->query()
    ->kind('Person')
    ->limit($limit);
$results = $datastore->runQuery($query);

foreach ($results as $key => $result) {
    if ($key === $limit) {
        break;
    }

    echo $result->get();
}

Would we be able to consider not automatically paging when a limit/cursor are set, or document the behavior more clearly?

Thanks! :)

[kaliseo]

Seriously ? oO One big problem identified is that if you have thousands of entities, it will cost a lot if i use someting like <=x

[jdpedrie]

@dwsupplee Maybe we should change limit to set a true limit on the result set (essentially prevent paging), and add a resultsPerPage method to do what we're doing now?

[dwsupplee]

Closed by #200

[tmatsuo]

JFYI our tests pass now