Skip to content

[Datastore] Cleanups for documentation #205

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tmatsuo merged 1 commit into from
Oct 20, 2016
Merged

[Datastore] Cleanups for documentation #205

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 26 additions & 31 deletions datastore/api/src/functions/concepts.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,8 @@

namespace Google\Cloud\Samples\Datastore;

use DateTime;
use Generator;
use Google;
// [START datastore_use]
use Google\Cloud\Datastore\DatastoreClient;
// [END datastore_use]
Expand All @@ -43,7 +43,7 @@ function initialize_client()
* Create a Datastore entity.
*
* @param DatastoreClient $datastore
* @return Google\Cloud\Datastore\Entity
* @return Entity
*/
function basic_entity(DatastoreClient $datastore)
{
Expand All @@ -62,7 +62,7 @@ function basic_entity(DatastoreClient $datastore)
* Create a Datastore entity and upsert it.
*
* @param DatastoreClient $datastore
* @return Google\Cloud\Datastore\Entity
* @return Entity
*/
function upsert(DatastoreClient $datastore)
{
Expand All @@ -85,7 +85,7 @@ function upsert(DatastoreClient $datastore)
* an entity with the same key.
*
* @param DatastoreClient $datastore
* @return Google\Cloud\Datastore\Entity
* @return Entity
*/
function insert(DatastoreClient $datastore)
{
Expand All @@ -105,7 +105,7 @@ function insert(DatastoreClient $datastore)
* Look up a Datastore entity with the given key.
*
* @param DatastoreClient $datastore
* @return Google\Cloud\Datastore\Entity|null
* @return Entity|null
*/
function lookup(DatastoreClient $datastore)
{
Expand All @@ -120,7 +120,7 @@ function lookup(DatastoreClient $datastore)
* Update a Datastore entity in a transaction.
*
* @param DatastoreClient $datastore
* @return Google\Cloud\Datastore\Entity|null
* @return Entity|null
*/
function update(DatastoreClient $datastore)
{
Expand Down Expand Up @@ -152,7 +152,7 @@ function delete(DatastoreClient $datastore, Key $taskKey)
* Upsert multiple Datastore entities.
*
* @param DatastoreClient $datastore
* @param array <Google\Cloud\Datastore\Entity> $tasks
* @param array <Entity> $tasks
*/
function batch_upsert(DatastoreClient $datastore, array $tasks)
{
Expand All @@ -166,7 +166,7 @@ function batch_upsert(DatastoreClient $datastore, array $tasks)
*
* @param DatastoreClient $datastore
* @param array <Key> $keys
* @return array <Google\Cloud\Datastore\Entity>
* @return array <Entity>
*/
function batch_lookup(DatastoreClient $datastore, array $keys)
{
Expand Down Expand Up @@ -258,7 +258,7 @@ function key_with_multilevel_parent(DatastoreClient $datastore)
*
* @param DatastoreClient $datastore
* @param Key $key
* @return Google\Cloud\Datastore\Entity
* @return Entity
*/
function properties(DatastoreClient $datastore, Key $key)
{
Expand All @@ -267,7 +267,7 @@ function properties(DatastoreClient $datastore, Key $key)
$key,
[
'category' => 'Personal',
'created' => new \DateTime(),
'created' => new DateTime(),
'done' => false,
'priority' => 4,
'percent_complete' => 10.0,
Expand All @@ -284,7 +284,7 @@ function properties(DatastoreClient $datastore, Key $key)
*
* @param DatastoreClient $datastore
* @param Key $key
* @return Google\Cloud\Datastore\Entity
* @return Entity
*/
function array_value(DatastoreClient $datastore, Key $key)
{
Expand Down Expand Up @@ -322,7 +322,7 @@ function basic_query(DatastoreClient $datastore)
* Run a given query.
*
* @param DatastoreClient $datastore
* @return Generator <Google\Cloud\Datastore\Entity>
* @return Generator <Entity>
*/
function run_query(DatastoreClient $datastore, Query $query)
{
Expand Down Expand Up @@ -473,8 +473,7 @@ function keys_only_query(DatastoreClient $datastore)
{
// [START keys_only_query]
$query = $datastore->query()
->keysOnly()
->limit(1);
->keysOnly();
// [END keys_only_query]
return $query;
}
Expand Down Expand Up @@ -508,7 +507,7 @@ function run_projection_query(DatastoreClient $datastore, Query $query)
$priorities = array();
$percentCompletes = array();
$result = $datastore->runQuery($query);
/* @var Google\Cloud\Datastore\Entity $task */
/* @var Entity $task */
foreach ($result as $task) {
$priorities[] = $task['priority'];
$percentCompletes[] = $task['percent_complete'];
Expand Down Expand Up @@ -586,39 +585,35 @@ function limit(DatastoreClient $datastore)
return $query;
}

// [START cursor_paging]
/**
* Fetch a query cursor.
*
* @param DatastoreClient $datastore
* @param string $pageSize
* @param string $pageCursor
* @return string $nextPageCursor
* @return array
*/
function cursor_paging(DatastoreClient $datastore, $pageSize, $pageCursor = '')
{
// [START cursor_paging]
$query = $datastore->query()
->kind('Task')
->limit($pageSize)
->start($pageCursor);
$result = $datastore->runQuery($query);
$nextPageCursor = '';
// In this example, it collects all the entities in an array. This will
// consume lot of memory if there are many entities. The query result is a
// generator, so you can write a memory-efficient loop if you don't
// collect all the entities in the array.
$entities = [];
/* @var Google\Cloud\Datastore\Entity $entity */
/* @var Entity $entity */
foreach ($result as $entity) {
$nextPageCursor = $entity->cursor();
$entities[] = $entity;
}
// [END cursor_paging]
return array(
'nextPageCursor' => $nextPageCursor,
'entities' => $entities
);
}
// [END cursor_paging]

/**
* Create a query with inequality range filters on the same property.
Expand All @@ -631,8 +626,8 @@ function inequality_range(DatastoreClient $datastore)
// [START inequality_range]
$query = $datastore->query()
->kind('Task')
->filter('created', '>', new \DateTime('1990-01-01T00:00:00z'))
->filter('created', '<', new \DateTime('2000-12-31T23:59:59z'));
->filter('created', '>', new DateTime('1990-01-01T00:00:00z'))
->filter('created', '<', new DateTime('2000-12-31T23:59:59z'));
// [END inequality_range]
return $query;
}
Expand All @@ -649,7 +644,7 @@ function inequality_invalid(DatastoreClient $datastore)
$query = $datastore->query()
->kind('Task')
->filter('priority', '>', 3)
->filter('created', '>', new \DateTime('1990-01-01T00:00:00z'));
->filter('created', '>', new DateTime('1990-01-01T00:00:00z'));
// [END inequality_invalid]
return $query;
}
Expand All @@ -668,8 +663,8 @@ function equal_and_inequality_range(DatastoreClient $datastore)
->kind('Task')
->filter('priority', '=', 4)
->filter('done', '=', false)
->filter('created', '>', new \DateTime('1990-01-01T00:00:00z'))
->filter('created', '<', new \DateTime('2000-12-31T23:59:59z'));
->filter('created', '>', new DateTime('1990-01-01T00:00:00z'))
->filter('created', '<', new DateTime('2000-12-31T23:59:59z'));
// [END equal_and_inequality_range]
return $query;
}
Expand Down Expand Up @@ -747,7 +742,7 @@ function unindexed_property_query(DatastoreClient $datastore)
* Create an entity with two array properties.
*
* @param DatastoreClient $datastore
* @return Google\Cloud\Datastore\Entity
* @return Entity
*/
function exploding_properties(DatastoreClient $datastore)
{
Expand All @@ -757,7 +752,7 @@ function exploding_properties(DatastoreClient $datastore)
[
'tags' => ['fun', 'programming', 'learn'],
'collaborators' => ['alice', 'bob', 'charlie'],
'created' => new \DateTime(),
'created' => new DateTime(),
]
);
// [END exploding_properties]
Expand Down Expand Up @@ -853,7 +848,7 @@ function get_task_list_entities(DatastoreClient $datastore)
$taskListKey = $datastore->key('TaskList', 'default');
$query = $datastore->query()
->kind('Task')
->filter('__key__', Query::OP_HAS_ANCESTOR, $taskListKey);
->hasAncestor($taskListKey);
$result = $transaction->runQuery($query);
$taskListEntities = [];
/* @var Entity $task */
Expand Down
50 changes: 27 additions & 23 deletions datastore/api/test/ConceptsTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@

namespace Google\Cloud\Samples\Datastore;

use Generator;
use Google;
use Google\Cloud\Datastore\DatastoreClient;
use Google\Cloud\Datastore\Entity;
Expand Down Expand Up @@ -329,7 +330,7 @@ public function testArrayValue()
->projection(['tags', 'collaborators'])
->filter('collaborators', '<', 'charlie');
$result = self::$datastore->runQuery($query);
$this->assertInstanceOf(\Generator::class, $result);
$this->assertInstanceOf(Generator::class, $result);
$num = 0;
/* @var Entity $e */
foreach ($result as $e) {
Expand Down Expand Up @@ -612,7 +613,7 @@ public function testAncestorQuery()
$query = ancestor_query(self::$datastore);
$this->assertInstanceOf(Query::class, $query);
$result = self::$datastore->runQuery($query);
$this->assertInstanceOf(\Generator::class, $result);
$this->assertInstanceOf(Generator::class, $result);
$found = false;
foreach ($result as $e) {
$found = true;
Expand Down Expand Up @@ -655,14 +656,17 @@ public function testKeysOnlyQuery()
$entity['prop'] = 'value';
self::$keys[] = $key;
self::$datastore->upsert($entity);
$this->runEventuallyConsistentTest(function () {
$this->runEventuallyConsistentTest(function () use ($key) {
$query = keys_only_query(self::$datastore);
$result = self::$datastore->runQuery($query);
$this->assertInstanceOf(\Generator::class, $result);
$this->assertInstanceOf(Generator::class, $result);
$found = false;
/* @var Entity $e */
foreach ($result as $e) {
$this->assertNull($e['prop']);
$this->assertEquals($key->path(), $e->key()->path());
$found = true;
break;
}
self::assertTrue($found);
});
Expand All @@ -680,7 +684,7 @@ public function testProjectionQuery()
$this->runEventuallyConsistentTest(function () {
$query = projection_query(self::$datastore);
$result = self::$datastore->runQuery($query);
$this->assertInstanceOf(\Generator::class, $result);
$this->assertInstanceOf(Generator::class, $result);
$found = false;
foreach ($result as $e) {
$this->assertEquals(4, $e['priority']);
Expand Down Expand Up @@ -726,7 +730,7 @@ public function testDistinctOn()
$this->runEventuallyConsistentTest(function () use ($key1) {
$query = distinct_on(self::$datastore);
$result = self::$datastore->runQuery($query);
$this->assertInstanceOf(\Generator::class, $result);
$this->assertInstanceOf(Generator::class, $result);
$num = 0;
/* @var Entity $e */
foreach ($result as $e) {
Expand All @@ -752,7 +756,7 @@ public function testArrayValueFilters()
sleep(5);
$query = array_value_inequality_range(self::$datastore);
$result = self::$datastore->runQuery($query);
$this->assertInstanceOf(\Generator::class, $result);
$this->assertInstanceOf(Generator::class, $result);
/* @var Entity $e */
foreach ($result as $e) {
$this->fail(
Expand All @@ -765,7 +769,7 @@ public function testArrayValueFilters()
$this->runEventuallyConsistentTest(function () use ($key) {
$query = array_value_equality(self::$datastore);
$result = self::$datastore->runQuery($query);
$this->assertInstanceOf(\Generator::class, $result);
$this->assertInstanceOf(Generator::class, $result);
$num = 0;
/* @var Entity $e */
foreach ($result as $e) {
Expand All @@ -789,7 +793,7 @@ public function testLimit()
$this->runEventuallyConsistentTest(function () {
$query = limit(self::$datastore);
$result = self::$datastore->runQuery($query);
$this->assertInstanceOf(\Generator::class, $result);
$this->assertInstanceOf(Generator::class, $result);
$num = 0;
/* @var Entity $e */
foreach ($result as $e) {
Expand Down Expand Up @@ -821,8 +825,8 @@ public function testInequalityRange()
{
$query = inequality_range(self::$datastore);
$result = self::$datastore->runQuery($query);
$this->assertInstanceOf(\Generator::class, $result);
/* @var Google\Cloud\Datastore\Entity $e */
$this->assertInstanceOf(Generator::class, $result);
/* @var Entity $e */
foreach ($result as $e) {
$this->fail(
sprintf(
Expand All @@ -840,8 +844,8 @@ public function testInequalityInvalid()
{
$query = inequality_invalid(self::$datastore);
$result = self::$datastore->runQuery($query);
$this->assertInstanceOf(\Generator::class, $result);
/* @var Google\Cloud\Datastore\Entity $e */
$this->assertInstanceOf(Generator::class, $result);
/* @var Entity $e */
foreach ($result as $e) {
$this->fail(
sprintf(
Expand All @@ -856,8 +860,8 @@ public function testEqualAndInequalityRange()
{
$query = equal_and_inequality_range(self::$datastore);
$result = self::$datastore->runQuery($query);
$this->assertInstanceOf(\Generator::class, $result);
/* @var Google\Cloud\Datastore\Entity $e */
$this->assertInstanceOf(Generator::class, $result);
/* @var Entity $e */
foreach ($result as $e) {
$this->fail(
sprintf(
Expand All @@ -872,8 +876,8 @@ public function testInequalitySort()
{
$query = inequality_sort(self::$datastore);
$result = self::$datastore->runQuery($query);
$this->assertInstanceOf(\Generator::class, $result);
/* @var Google\Cloud\Datastore\Entity $e */
$this->assertInstanceOf(Generator::class, $result);
/* @var Entity $e */
foreach ($result as $e) {
$this->fail(
sprintf(
Expand All @@ -891,8 +895,8 @@ public function testInequalitySortInvalidNotSame()
{
$query = inequality_sort_invalid_not_same(self::$datastore);
$result = self::$datastore->runQuery($query);
$this->assertInstanceOf(\Generator::class, $result);
/* @var Google\Cloud\Datastore\Entity $e */
$this->assertInstanceOf(Generator::class, $result);
/* @var Entity $e */
foreach ($result as $e) {
$this->fail(
sprintf(
Expand All @@ -910,8 +914,8 @@ public function testInequalitySortInvalidNotFirst()
{
$query = inequality_sort_invalid_not_first(self::$datastore);
$result = self::$datastore->runQuery($query);
$this->assertInstanceOf(\Generator::class, $result);
/* @var Google\Cloud\Datastore\Entity $e */
$this->assertInstanceOf(Generator::class, $result);
/* @var Entity $e */
foreach ($result as $e) {
$this->fail(
sprintf(
Expand All @@ -926,8 +930,8 @@ public function testUnindexedPropertyQuery()
{
$query = unindexed_property_query(self::$datastore);
$result = self::$datastore->runQuery($query);
$this->assertInstanceOf(\Generator::class, $result);
/* @var Google\Cloud\Datastore\Entity $e */
$this->assertInstanceOf(Generator::class, $result);
/* @var Entity $e */
foreach ($result as $e) {
$this->fail(
sprintf(
Expand Down