docs: Added additional docs for executeUpdate (#2269)

* docs: Added additional docs for executeUpdate * Added notes that executeUpdate should be used for insert, update and delete statements, which should help quick searching of the docs. * Added an example update using a struct * Added links in the docs to DML guide * Removing accidental imports * Update Spanner/src/Transaction.php Co-Authored-By: John Pedrie <[email protected]> * Update Spanner/src/Transaction.php Co-Authored-By: John Pedrie <[email protected]> * Update Spanner/src/Transaction.php Co-Authored-By: John Pedrie <[email protected]> * Update Spanner/src/Transaction.php Co-Authored-By: John Pedrie <[email protected]> * Update Spanner/tests/Snippet/TransactionTest.php Co-Authored-By: John Pedrie <[email protected]> * Fixes snippet assertions * Update Spanner/src/Transaction.php Co-Authored-By: John Pedrie <[email protected]> * Update Spanner/src/Transaction.php Co-Authored-By: John Pedrie <[email protected]> * Moving see statement * Using fluent syntax in snippet
googleapis · Aug 29, 2019 · b33bf33 · b33bf33
1 parent f98eaca
commit b33bf33
Show file tree

Hide file tree

Showing 2 changed files with 84 additions and 1 deletion.
diff --git a/Spanner/src/Transaction.php b/Spanner/src/Transaction.php
@@ -312,7 +312,9 @@ public function delete($table, KeySet $keySet)
      *
      * Data Manipulation Language (DML) allows you to execute statements which
      * modify the state of the database (i.e. inserting, updating or deleting
-     * rows).
+     * rows). DML supports INSERT, UPDATE and DELETE statements. For
+     * more on DML syntax, visit the
+     * [DML syntax guide](https://cloud.google.com/spanner/docs/dml-syntax).
      *
      * To execute a SQL query (such as a SELECT), use
      * {@see Google\Cloud\Spanner\Transaction::execute()}.
@@ -333,8 +335,32 @@ public function delete($table, KeySet $keySet)
      * ]);
      * ```
      *
+     * ```
+     * // Example of executeUpdate while using DML Structs
+     * $statement = "UPDATE Posts SET title = 'Updated Title' " .
+     *     "WHERE STRUCT<Title STRING, Content STRING>(Title, Content) = @post";
+     *
+     * $postValue = new StructValue();
+     * $postValue->add('Title', 'Updated Title')
+     *           ->add('Content', 'Sample Content');
+     *
+     * $postType = new StructType();
+     * $postType->add('Title', Database::TYPE_STRING)
+     *          ->add('Content', Database::TYPE_STRING);
+     *
+     * $modifiedRowCount = $transaction->executeUpdate($statement, [
+     *     'parameters' => [
+     *         'post' => $postValue
+     *     ],
+     *     'types' => [
+     *         'post' => $postType
+     *     ]
+     * ]);
+     * ```
+     *
      * @codingStandardsIgnoreStart
      * @see https://cloud.google.com/spanner/reference/rpc/google.spanner.v1#google.spanner.v1.ExecuteSqlRequest ExecuteSqlRequest
+     * @see https://cloud.google.com/spanner/docs/dml-syntax DML Syntax Guide
      * @codingStandardsIgnoreEnd
      *
      * @param string $sql The query string to execute.

diff --git a/Spanner/tests/Snippet/TransactionTest.php b/Spanner/tests/Snippet/TransactionTest.php
@@ -26,6 +26,8 @@
 use Google\Cloud\Spanner\Operation;
 use Google\Cloud\Spanner\Result;
 use Google\Cloud\Spanner\Session\Session;
+use Google\Cloud\Spanner\StructType;
+use Google\Cloud\Spanner\StructValue;
 use Google\Cloud\Spanner\Tests\OperationRefreshTrait;
 use Google\Cloud\Spanner\Tests\ResultGeneratorTrait;
 use Google\Cloud\Spanner\Timestamp;
@@ -116,6 +118,61 @@ public function testExecuteUpdate()
         $this->assertEquals(1, $res->returnVal());
     }
 
+    public function testExecuteUpdateWithStruct()
+    {
+        $expectedSql = "UPDATE Posts SET title = 'Updated Title' WHERE " .
+            "STRUCT<Title STRING, Content STRING>(Title, Content) = @post";
+
+        $expectedParams = [
+            'post' => ["Updated Title", "Sample Content"]
+        ];
+        $expectedStructData = [
+            [
+                "name" => "Title",
+                "type" => [
+                    "code" => Database::TYPE_STRING
+                ]
+            ],
+            [
+                "name" => "Content",
+                "type" => [
+                    "code" => Database::TYPE_STRING
+                ]
+            ]
+        ];
+
+        $this->connection->executeStreamingSql(
+            Argument::allOf(
+                Argument::withEntry('sql', $expectedSql),
+                Argument::withEntry('params', $expectedParams),
+                Argument::withEntry(
+                    'paramTypes',
+                    Argument::withEntry(
+                        'post',
+                        Argument::withEntry(
+                            'structType',
+                            Argument::withEntry('fields', Argument::is($expectedStructData))
+                        )
+                    )
+                )
+            )
+        )
+            ->shouldBeCalled()
+            ->willReturn($this->resultGenerator(true));
+
+        $this->refreshOperation($this->transaction, $this->connection->reveal());
+
+        $snippet = $this->snippetFromMethod(Transaction::class, 'executeUpdate', 1);
+        $snippet->addUse(Database::class);
+        $snippet->addUse(StructType::class);
+        $snippet->addUse(StructValue::class);
+
+        $snippet->addLocal('transaction', $this->transaction);
+        $res = $snippet->invoke('modifiedRowCount');
+
+        $this->assertEquals(1, $res->returnVal());
+    }
+
     public function testExecuteUpdateBatch()
     {
         $this->connection->executeBatchDml(Argument::any())