feat: [Datastore] add sample for GqlQuery (#1684)

Author: vishwarajanand

datastore/api/src/functions/concepts.php

@@ -22,6 +22,7 @@
 use Google\Cloud\Datastore\Entity;
 use Google\Cloud\Datastore\EntityIterator;
 use Google\Cloud\Datastore\Key;
+use Google\Cloud\Datastore\Query\GqlQuery;
 use Google\Cloud\Datastore\Query\Query;
 
 /**
@@ -314,16 +315,46 @@ function basic_query(DatastoreClient $datastore)
     return $query;
 }
 
+/**
+ * Create a basic Datastore Gql query.
+ *
+ * @param DatastoreClient $datastore
+ * @return GqlQuery
+ */
+function basic_gql_query(DatastoreClient $datastore)
+{
+    // [START datastore_basic_gql_query]
+    $gql = <<<EOF
+SELECT * from Task
+where
+    done = @a
+    AND priority >= @b
+order by
+    priority desc
+EOF;
+    $query = $datastore->gqlQuery($gql, [
+        'bindings' => [
+            'a' => false,
+            'b' => 4,
+        ],
+    ]);
+    // [END datastore_basic_gql_query]
+    return $query;
+}
+
 /**
  * Run a given query.
  *
  * @param DatastoreClient $datastore
+ * @param Query|GqlQuery $query
  * @return EntityIterator<Entity>
  */
-function run_query(DatastoreClient $datastore, Query $query)
+function run_query(DatastoreClient $datastore, $query)
 {
     // [START datastore_run_query]
+    // [START datastore_run_gql_query]
     $result = $datastore->runQuery($query);
+    // [END datastore_run_gql_query]
     // [END datastore_run_query]
     return $result;
 }

datastore/api/test/ConceptsTest.php

@@ -20,6 +20,7 @@
 use Iterator;
 use Google\Cloud\Datastore\DatastoreClient;
 use Google\Cloud\Datastore\Entity;
+use Google\Cloud\Datastore\Query\GqlQuery;
 use Google\Cloud\Datastore\Query\Query;
 use Google\Cloud\TestUtils\EventuallyConsistentTestTrait;
 use PHPUnit\Framework\TestCase;
@@ -417,6 +418,37 @@ function () use ($key1, $key2, $query) {
             });
     }
 
+    public function testRunGqlQuery()
+    {
+        $key1 = self::$datastore->key('Task', generateRandomString());
+        $key2 = self::$datastore->key('Task', generateRandomString());
+        $entity1 = self::$datastore->entity($key1);
+        $entity2 = self::$datastore->entity($key2);
+        $entity1['priority'] = 4;
+        $entity1['done'] = false;
+        $entity2['priority'] = 5;
+        $entity2['done'] = false;
+        self::$keys = [$key1, $key2];
+        self::$datastore->upsertBatch([$entity1, $entity2]);
+        $query = basic_gql_query(self::$datastore);
+        $this->assertInstanceOf(GqlQuery::class, $query);
+
+        $this->runEventuallyConsistentTest(
+            function () use ($key1, $key2, $query) {
+                $result = run_query(self::$datastore, $query);
+                $num = 0;
+                $entities = [];
+                /* @var Entity $e */
+                foreach ($result as $e) {
+                    $entities[] = $e;
+                    $num += 1;
+                }
+                self::assertEquals(2, $num);
+                $this->assertTrue($entities[0]->key()->path() == $key2->path());
+                $this->assertTrue($entities[1]->key()->path() == $key1->path());
+            });
+    }
+
     public function testPropertyFilter()
     {
         $key1 = self::$datastore->key('Task', generateRandomString());