Skip to content

Commit a0322ba

Browse files
author
Takashi Matsuo
authored
[Datastore] Cleanups for documentation (GoogleCloudPlatform#205)
1 parent 6e75966 commit a0322ba

File tree

2 files changed

+53
-54
lines changed

2 files changed

+53
-54
lines changed

‎datastore/api/src/functions/concepts.php‎

Lines changed: 26 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,8 @@
1717

1818
namespace Google\Cloud\Samples\Datastore;
1919

20+
use DateTime;
2021
use Generator;
21-
use Google;
2222
// [START datastore_use]
2323
use Google\Cloud\Datastore\DatastoreClient;
2424
// [END datastore_use]
@@ -43,7 +43,7 @@ function initialize_client()
4343
* Create a Datastore entity.
4444
*
4545
* @param DatastoreClient $datastore
46-
* @return Google\Cloud\Datastore\Entity
46+
* @return Entity
4747
*/
4848
function basic_entity(DatastoreClient $datastore)
4949
{
@@ -62,7 +62,7 @@ function basic_entity(DatastoreClient $datastore)
6262
* Create a Datastore entity and upsert it.
6363
*
6464
* @param DatastoreClient $datastore
65-
* @return Google\Cloud\Datastore\Entity
65+
* @return Entity
6666
*/
6767
function upsert(DatastoreClient $datastore)
6868
{
@@ -85,7 +85,7 @@ function upsert(DatastoreClient $datastore)
8585
* an entity with the same key.
8686
*
8787
* @param DatastoreClient $datastore
88-
* @return Google\Cloud\Datastore\Entity
88+
* @return Entity
8989
*/
9090
function insert(DatastoreClient $datastore)
9191
{
@@ -105,7 +105,7 @@ function insert(DatastoreClient $datastore)
105105
* Look up a Datastore entity with the given key.
106106
*
107107
* @param DatastoreClient $datastore
108-
* @return Google\Cloud\Datastore\Entity|null
108+
* @return Entity|null
109109
*/
110110
function lookup(DatastoreClient $datastore)
111111
{
@@ -120,7 +120,7 @@ function lookup(DatastoreClient $datastore)
120120
* Update a Datastore entity in a transaction.
121121
*
122122
* @param DatastoreClient $datastore
123-
* @return Google\Cloud\Datastore\Entity|null
123+
* @return Entity|null
124124
*/
125125
function update(DatastoreClient $datastore)
126126
{
@@ -152,7 +152,7 @@ function delete(DatastoreClient $datastore, Key $taskKey)
152152
* Upsert multiple Datastore entities.
153153
*
154154
* @param DatastoreClient $datastore
155-
* @param array <Google\Cloud\Datastore\Entity> $tasks
155+
* @param array <Entity> $tasks
156156
*/
157157
function batch_upsert(DatastoreClient $datastore, array $tasks)
158158
{
@@ -166,7 +166,7 @@ function batch_upsert(DatastoreClient $datastore, array $tasks)
166166
*
167167
* @param DatastoreClient $datastore
168168
* @param array <Key> $keys
169-
* @return array <Google\Cloud\Datastore\Entity>
169+
* @return array <Entity>
170170
*/
171171
function batch_lookup(DatastoreClient $datastore, array $keys)
172172
{
@@ -258,7 +258,7 @@ function key_with_multilevel_parent(DatastoreClient $datastore)
258258
*
259259
* @param DatastoreClient $datastore
260260
* @param Key $key
261-
* @return Google\Cloud\Datastore\Entity
261+
* @return Entity
262262
*/
263263
function properties(DatastoreClient $datastore, Key $key)
264264
{
@@ -267,7 +267,7 @@ function properties(DatastoreClient $datastore, Key $key)
267267
$key,
268268
[
269269
'category' => 'Personal',
270-
'created' => new \DateTime(),
270+
'created' => new DateTime(),
271271
'done' => false,
272272
'priority' => 4,
273273
'percent_complete' => 10.0,
@@ -284,7 +284,7 @@ function properties(DatastoreClient $datastore, Key $key)
284284
*
285285
* @param DatastoreClient $datastore
286286
* @param Key $key
287-
* @return Google\Cloud\Datastore\Entity
287+
* @return Entity
288288
*/
289289
function array_value(DatastoreClient $datastore, Key $key)
290290
{
@@ -322,7 +322,7 @@ function basic_query(DatastoreClient $datastore)
322322
* Run a given query.
323323
*
324324
* @param DatastoreClient $datastore
325-
* @return Generator <Google\Cloud\Datastore\Entity>
325+
* @return Generator <Entity>
326326
*/
327327
function run_query(DatastoreClient $datastore, Query $query)
328328
{
@@ -473,8 +473,7 @@ function keys_only_query(DatastoreClient $datastore)
473473
{
474474
// [START keys_only_query]
475475
$query = $datastore->query()
476-
->keysOnly()
477-
->limit(1);
476+
->keysOnly();
478477
// [END keys_only_query]
479478
return $query;
480479
}
@@ -508,7 +507,7 @@ function run_projection_query(DatastoreClient $datastore, Query $query)
508507
$priorities = array();
509508
$percentCompletes = array();
510509
$result = $datastore->runQuery($query);
511-
/* @var Google\Cloud\Datastore\Entity $task */
510+
/* @var Entity $task */
512511
foreach ($result as $task) {
513512
$priorities[] = $task['priority'];
514513
$percentCompletes[] = $task['percent_complete'];
@@ -586,39 +585,35 @@ function limit(DatastoreClient $datastore)
586585
return $query;
587586
}
588587

588+
// [START cursor_paging]
589589
/**
590590
* Fetch a query cursor.
591591
*
592592
* @param DatastoreClient $datastore
593593
* @param string $pageSize
594594
* @param string $pageCursor
595-
* @return string $nextPageCursor
595+
* @return array
596596
*/
597597
function cursor_paging(DatastoreClient $datastore, $pageSize, $pageCursor = '')
598598
{
599-
// [START cursor_paging]
600599
$query = $datastore->query()
601600
->kind('Task')
602601
->limit($pageSize)
603602
->start($pageCursor);
604603
$result = $datastore->runQuery($query);
605604
$nextPageCursor = '';
606-
// In this example, it collects all the entities in an array. This will
607-
// consume lot of memory if there are many entities. The query result is a
608-
// generator, so you can write a memory-efficient loop if you don't
609-
// collect all the entities in the array.
610605
$entities = [];
611-
/* @var Google\Cloud\Datastore\Entity $entity */
606+
/* @var Entity $entity */
612607
foreach ($result as $entity) {
613608
$nextPageCursor = $entity->cursor();
614609
$entities[] = $entity;
615610
}
616-
// [END cursor_paging]
617611
return array(
618612
'nextPageCursor' => $nextPageCursor,
619613
'entities' => $entities
620614
);
621615
}
616+
// [END cursor_paging]
622617

623618
/**
624619
* Create a query with inequality range filters on the same property.
@@ -631,8 +626,8 @@ function inequality_range(DatastoreClient $datastore)
631626
// [START inequality_range]
632627
$query = $datastore->query()
633628
->kind('Task')
634-
->filter('created', '>', new \DateTime('1990-01-01T00:00:00z'))
635-
->filter('created', '<', new \DateTime('2000-12-31T23:59:59z'));
629+
->filter('created', '>', new DateTime('1990-01-01T00:00:00z'))
630+
->filter('created', '<', new DateTime('2000-12-31T23:59:59z'));
636631
// [END inequality_range]
637632
return $query;
638633
}
@@ -649,7 +644,7 @@ function inequality_invalid(DatastoreClient $datastore)
649644
$query = $datastore->query()
650645
->kind('Task')
651646
->filter('priority', '>', 3)
652-
->filter('created', '>', new \DateTime('1990-01-01T00:00:00z'));
647+
->filter('created', '>', new DateTime('1990-01-01T00:00:00z'));
653648
// [END inequality_invalid]
654649
return $query;
655650
}
@@ -668,8 +663,8 @@ function equal_and_inequality_range(DatastoreClient $datastore)
668663
->kind('Task')
669664
->filter('priority', '=', 4)
670665
->filter('done', '=', false)
671-
->filter('created', '>', new \DateTime('1990-01-01T00:00:00z'))
672-
->filter('created', '<', new \DateTime('2000-12-31T23:59:59z'));
666+
->filter('created', '>', new DateTime('1990-01-01T00:00:00z'))
667+
->filter('created', '<', new DateTime('2000-12-31T23:59:59z'));
673668
// [END equal_and_inequality_range]
674669
return $query;
675670
}
@@ -747,7 +742,7 @@ function unindexed_property_query(DatastoreClient $datastore)
747742
* Create an entity with two array properties.
748743
*
749744
* @param DatastoreClient $datastore
750-
* @return Google\Cloud\Datastore\Entity
745+
* @return Entity
751746
*/
752747
function exploding_properties(DatastoreClient $datastore)
753748
{
@@ -757,7 +752,7 @@ function exploding_properties(DatastoreClient $datastore)
757752
[
758753
'tags' => ['fun', 'programming', 'learn'],
759754
'collaborators' => ['alice', 'bob', 'charlie'],
760-
'created' => new \DateTime(),
755+
'created' => new DateTime(),
761756
]
762757
);
763758
// [END exploding_properties]
@@ -853,7 +848,7 @@ function get_task_list_entities(DatastoreClient $datastore)
853848
$taskListKey = $datastore->key('TaskList', 'default');
854849
$query = $datastore->query()
855850
->kind('Task')
856-
->filter('__key__', Query::OP_HAS_ANCESTOR, $taskListKey);
851+
->hasAncestor($taskListKey);
857852
$result = $transaction->runQuery($query);
858853
$taskListEntities = [];
859854
/* @var Entity $task */

‎datastore/api/test/ConceptsTest.php‎

Lines changed: 27 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717

1818
namespace Google\Cloud\Samples\Datastore;
1919

20+
use Generator;
2021
use Google;
2122
use Google\Cloud\Datastore\DatastoreClient;
2223
use Google\Cloud\Datastore\Entity;
@@ -329,7 +330,7 @@ public function testArrayValue()
329330
->projection(['tags', 'collaborators'])
330331
->filter('collaborators', '<', 'charlie');
331332
$result = self::$datastore->runQuery($query);
332-
$this->assertInstanceOf(\Generator::class, $result);
333+
$this->assertInstanceOf(Generator::class, $result);
333334
$num = 0;
334335
/* @var Entity $e */
335336
foreach ($result as $e) {
@@ -612,7 +613,7 @@ public function testAncestorQuery()
612613
$query = ancestor_query(self::$datastore);
613614
$this->assertInstanceOf(Query::class, $query);
614615
$result = self::$datastore->runQuery($query);
615-
$this->assertInstanceOf(\Generator::class, $result);
616+
$this->assertInstanceOf(Generator::class, $result);
616617
$found = false;
617618
foreach ($result as $e) {
618619
$found = true;
@@ -655,14 +656,17 @@ public function testKeysOnlyQuery()
655656
$entity['prop'] = 'value';
656657
self::$keys[] = $key;
657658
self::$datastore->upsert($entity);
658-
$this->runEventuallyConsistentTest(function () {
659+
$this->runEventuallyConsistentTest(function () use ($key) {
659660
$query = keys_only_query(self::$datastore);
660661
$result = self::$datastore->runQuery($query);
661-
$this->assertInstanceOf(\Generator::class, $result);
662+
$this->assertInstanceOf(Generator::class, $result);
662663
$found = false;
664+
/* @var Entity $e */
663665
foreach ($result as $e) {
664666
$this->assertNull($e['prop']);
667+
$this->assertEquals($key->path(), $e->key()->path());
665668
$found = true;
669+
break;
666670
}
667671
self::assertTrue($found);
668672
});
@@ -680,7 +684,7 @@ public function testProjectionQuery()
680684
$this->runEventuallyConsistentTest(function () {
681685
$query = projection_query(self::$datastore);
682686
$result = self::$datastore->runQuery($query);
683-
$this->assertInstanceOf(\Generator::class, $result);
687+
$this->assertInstanceOf(Generator::class, $result);
684688
$found = false;
685689
foreach ($result as $e) {
686690
$this->assertEquals(4, $e['priority']);
@@ -726,7 +730,7 @@ public function testDistinctOn()
726730
$this->runEventuallyConsistentTest(function () use ($key1) {
727731
$query = distinct_on(self::$datastore);
728732
$result = self::$datastore->runQuery($query);
729-
$this->assertInstanceOf(\Generator::class, $result);
733+
$this->assertInstanceOf(Generator::class, $result);
730734
$num = 0;
731735
/* @var Entity $e */
732736
foreach ($result as $e) {
@@ -752,7 +756,7 @@ public function testArrayValueFilters()
752756
sleep(5);
753757
$query = array_value_inequality_range(self::$datastore);
754758
$result = self::$datastore->runQuery($query);
755-
$this->assertInstanceOf(\Generator::class, $result);
759+
$this->assertInstanceOf(Generator::class, $result);
756760
/* @var Entity $e */
757761
foreach ($result as $e) {
758762
$this->fail(
@@ -765,7 +769,7 @@ public function testArrayValueFilters()
765769
$this->runEventuallyConsistentTest(function () use ($key) {
766770
$query = array_value_equality(self::$datastore);
767771
$result = self::$datastore->runQuery($query);
768-
$this->assertInstanceOf(\Generator::class, $result);
772+
$this->assertInstanceOf(Generator::class, $result);
769773
$num = 0;
770774
/* @var Entity $e */
771775
foreach ($result as $e) {
@@ -789,7 +793,7 @@ public function testLimit()
789793
$this->runEventuallyConsistentTest(function () {
790794
$query = limit(self::$datastore);
791795
$result = self::$datastore->runQuery($query);
792-
$this->assertInstanceOf(\Generator::class, $result);
796+
$this->assertInstanceOf(Generator::class, $result);
793797
$num = 0;
794798
/* @var Entity $e */
795799
foreach ($result as $e) {
@@ -821,8 +825,8 @@ public function testInequalityRange()
821825
{
822826
$query = inequality_range(self::$datastore);
823827
$result = self::$datastore->runQuery($query);
824-
$this->assertInstanceOf(\Generator::class, $result);
825-
/* @var Google\Cloud\Datastore\Entity $e */
828+
$this->assertInstanceOf(Generator::class, $result);
829+
/* @var Entity $e */
826830
foreach ($result as $e) {
827831
$this->fail(
828832
sprintf(
@@ -840,8 +844,8 @@ public function testInequalityInvalid()
840844
{
841845
$query = inequality_invalid(self::$datastore);
842846
$result = self::$datastore->runQuery($query);
843-
$this->assertInstanceOf(\Generator::class, $result);
844-
/* @var Google\Cloud\Datastore\Entity $e */
847+
$this->assertInstanceOf(Generator::class, $result);
848+
/* @var Entity $e */
845849
foreach ($result as $e) {
846850
$this->fail(
847851
sprintf(
@@ -856,8 +860,8 @@ public function testEqualAndInequalityRange()
856860
{
857861
$query = equal_and_inequality_range(self::$datastore);
858862
$result = self::$datastore->runQuery($query);
859-
$this->assertInstanceOf(\Generator::class, $result);
860-
/* @var Google\Cloud\Datastore\Entity $e */
863+
$this->assertInstanceOf(Generator::class, $result);
864+
/* @var Entity $e */
861865
foreach ($result as $e) {
862866
$this->fail(
863867
sprintf(
@@ -872,8 +876,8 @@ public function testInequalitySort()
872876
{
873877
$query = inequality_sort(self::$datastore);
874878
$result = self::$datastore->runQuery($query);
875-
$this->assertInstanceOf(\Generator::class, $result);
876-
/* @var Google\Cloud\Datastore\Entity $e */
879+
$this->assertInstanceOf(Generator::class, $result);
880+
/* @var Entity $e */
877881
foreach ($result as $e) {
878882
$this->fail(
879883
sprintf(
@@ -891,8 +895,8 @@ public function testInequalitySortInvalidNotSame()
891895
{
892896
$query = inequality_sort_invalid_not_same(self::$datastore);
893897
$result = self::$datastore->runQuery($query);
894-
$this->assertInstanceOf(\Generator::class, $result);
895-
/* @var Google\Cloud\Datastore\Entity $e */
898+
$this->assertInstanceOf(Generator::class, $result);
899+
/* @var Entity $e */
896900
foreach ($result as $e) {
897901
$this->fail(
898902
sprintf(
@@ -910,8 +914,8 @@ public function testInequalitySortInvalidNotFirst()
910914
{
911915
$query = inequality_sort_invalid_not_first(self::$datastore);
912916
$result = self::$datastore->runQuery($query);
913-
$this->assertInstanceOf(\Generator::class, $result);
914-
/* @var Google\Cloud\Datastore\Entity $e */
917+
$this->assertInstanceOf(Generator::class, $result);
918+
/* @var Entity $e */
915919
foreach ($result as $e) {
916920
$this->fail(
917921
sprintf(
@@ -926,8 +930,8 @@ public function testUnindexedPropertyQuery()
926930
{
927931
$query = unindexed_property_query(self::$datastore);
928932
$result = self::$datastore->runQuery($query);
929-
$this->assertInstanceOf(\Generator::class, $result);
930-
/* @var Google\Cloud\Datastore\Entity $e */
933+
$this->assertInstanceOf(Generator::class, $result);
934+
/* @var Entity $e */
931935
foreach ($result as $e) {
932936
$this->fail(
933937
sprintf(

0 commit comments

Comments
 (0)